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TOPIC A. 2 - RT/T OPEPATCP^S GUIDE 


I. INTRODUCTION 

The single program that controls NASIS when the 8T/T 
version of that system is running is called the HT/T 
Monitor. The monitor is the only part of NRSIS with which 
the MT/T Operator coamunicates* 

Preparatory to initiating NRSIS, you must "log on” the TSS 
task (USERID) from which the HT/T version of NASTS is to be 
driven. 

After logon enter NASISHTT to bring up operational NASIS on 
NEBNASIS to bring up the experimental system. At this point 
TSS loads all the programs that comprise NASIS into memory. 
During initiation the MTT monitor reads in the 
NASIS. COHHRNDS (o) DATASET containing the LIHIT, NENS, and 
PGBSTOP monitcr commands (discussed later). After 
Initiation the monitor sends the following message to the 
operations terminals "KASIS COMHENCING”. At this point MTT 
will allow users to logon. 

To communicate with the monitor simply depress the ATTENTION 
key. The monitor will prompt you with a time-stamped 
guestion mack, for example: 

10:25 ? 

and unlock the keyboard. Note that while your keyboard is 
unlocked, NASIS is stopped. Waste no time in entering 
commands and newer, never leave your terminal sitting with 
its keyboard unlocked. 


II. MONITOR COMMANDS 

The monitor commands are comprised of a command name and, in 
some cases, additional operands. The monitor, when reading 
commands, reccgni-zes three "special" characters — two 
delimiters: (separators between command names and/or 

operands) comma and blank, and a character which may enclose 
an operand tc denote that that operand has "special" 
characters within it; the quote mark. The delimiters 
behave slightly differently — a string of contiguous blanks 
is interpeted as one delimiter, but two contiguous commas 
are interpeted as twc delimiters, and so forth. If you have 
to put blanks, commas or quotes within an operand, you must 
surround that operand with quote marks. In addition, if 
there are enclosed quotes, they must be paired inside the 
operand. For example 

*don*’t let this confuse you, it**s not really that 
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difficult’ 

is a valid quoted strinq contaiuinq embedded commas, blanks 
and quote marks* 

Gndec certain circumstances pressing the ATTENTION key vlll 
yield an exclamation-mark instead of the Monitor prompting 
message. When hitting ATTENTION does not qet you the 
Monitor’s question-mark prompt, enter the (TSS) command 
"PESET". After you see the ”>SOHEWHEPE" message, try 
hitting ATTENTION again. This time it will work. 

MSG NASISIC ,TElfT Sufficient Abbreviation 

(S.A.): M 

This coomand sends the message specified by the TEXT operand 
to the user who is on NASTS under the userid specified by 
the operand NASISID. Penember to surround the message text 
with quote marks if it contains commas, quote marks, or 
imbedded spaces. Examplet 

H NE01,’BEPE”S A MESSAGE.’ 

BCST TEXT S.A.: B 

This command sends the message specified by the TEXT operand 
to all the users logged on to NASIS. Example; 

BC ’DATACSll IS DOWS NSIC nOtAVAILABlE. • 

FORCE NASISID S, A. : F 

This command is used to terminate a NASIS user. The user 
(identified by NASISID) is sent the message 
TASK DELETED BY FOPCE ***** and then logged off. 
Example: 

F NE01 

KILL NASISID S.A.: K 

This command is used when FORCE fails. The KILL command may 
be reentered several times. The user (if the KILL works) 
will receive a program interrupt five at location zero, so 
you may ignore the message about that event. Example: 

KI HE01 

SHUTDOWN TIME S.A.T S 

This command terminates NASIS. The TIME operand specifies 
how long to wait before actually terminating the system 
(default is five minutes) . If the time specified is zero 
minutes NASIS is terminated immediately. This zero-time 
shutdown should be used only when absolutely necessary 
because it doesn’t give warning to the users. Normally, 
both you and the users get a message stating the time-of-day 
when the system will shut itself down. Should you change 
your mind about the shutdown enter another shutdown to 
override the previous one. (Cnly the last SHUTDOWN command 
entered has any effect.) Example; 

S 30 (To terminate NASIS in a half-hour) 
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LiaiT TERM,# S*A.: L 

This coromand allovs yota to limit the number of nsers of 
various sorts allowed on NASIS and to limit some of the 
resources of NASIS itself. The TEFa operand is either a 
"class" of NASISTDs (defined as the first two characters of 
the NASISID) or one cf the keywords "USERS", "PRINTS", 
"SEARCHES", "SOFTS" ot "EECCEDS". The keyword "USERS" is 
used to limit the total number of users allowed on NASIS and 
is the default value assumed if TEBH is omitted* Keyword 
"SEAPCHES" limits the size of a set a NASIS user may search 
on, "PRINTS" limits the size of a set he may print and so 
on. If the TEFM operand consists of exactly two characters 
it is assumed tc be a class name and the number of NASISIDs 
of that class allowed on NASIS will be limited. If the TERM 
operand consists of any other number of characters than two, 
it is assumed to be a keyword cr a part of a keyword. If 
the # operand is defaulted, the value 32767 is used. If the 
# operand is entered, TERM must be also entered, even if you 
use just a comma to default it* Examples: 

"liniT ,20 (Limit total number of users to 20) 

L S,50 (limit search set size to 50) 

LI NE,2 (limit "NE" NASISIDS to 2 ) 


USERS S.8.: U 

This command lists all the NASISIDs of the users currently 
using NASIS. Cnly those users completely logged on are 
listed, if there are users in the process of getting on, 
they will not show up cn the list from a USERS. 


NUSERS S.A.: N c/;N/: N/ 

This command tells you how many users are currently using 
NASIS. Unlike USERS, this command also tallies the users 
who ace in the process of logging on. 


DEBUG S.A.: D 

This command places tie Honitor into debugging mcde and 
returns to you with another prompting message. Only in this 
mode can you enter TSS ccmmands through the Monitor. 
Furthermore, in this mode the Monitor will continue 

prompting you until you respond with a null line (only a 
carriage-return) • This command should be used only when 
absolutely necessary as it ties up NASIS for as long as the 
operator terminal is being read from. 

NEWS "OFF"|TEXT S.A.: NE 

This command is used to control the sending and composition 
of the "news" which is sent to each user as he logs on to 
NASIS. Entering "OFF" as the operand terminates the sending 
of all news and deletes all the text from the news buffer. 
Entering anything but "OFF" causes whatever you enter to he 
added as the last line to whatever is already in the news 
buffer. If you enter no operands at all to NERS, it will 
add a carriage-return to the end of the news buffer. 
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xasples: 

NEirs OFF (Kills the sendinp of news) 

PGHSTOP "01i"!«OPF" s. A. P 

'This command tells the Monitor whether or not to stop 
whenever it enconnters a program interrupt {serious error)* 
If the operand entered is "OFF”, the Monitor will continue 
processing without pausino after a program interrupt. If 
"ON" is entered, the Monitor will pause at your operator 
terminal in ISS command mode after a program interrupt. 
This is normally used so that cne of the systems people can 
try to solve a problem. To continue NASIS execution after 
the pause, enter the <TSS) command "60", 

HECGBD lEVEL S.A. R 

The RECORD command is used to set the data recording level 
in the monitor. This level is used to determine which 
events, if any, the Monitor will attept to record on the 
SIPE tape, NOTE; Merelv turning on the Monitor’s 
recording mechanism does not ensure that the units will be 
recorded - SIPE itself most have been initiated by the TSS 
operator, 

IK 5 STATS "0N/"0FF" S.A. ST 

Khen this command with operand OFF is encountered, the 
Monitor turns cn an indicator telling BASIS not to take 
usage statistics. If CK is entered as the operand, that 
indicator is turned off, NOTE; This command may only be 
entered via the "NASIS. COMMANDS (0) " dataset. 
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CCRPAND SOPfiAFI 


COMMAND 

OPERANES 

FUNCTION 

(TSS conmands) 


HASISMTf 


Brinq up normal BASIS. 

NEWNASIS 


Erinq up experimental NASIS. 

GO 


Resume after interrupt pause. 

BESET 


Beset operator attention routine 

fNASIS connands) 


MSG 

NASISIB,TEXT 

Send message to specified user. 

BCST 

TEXT 

Send message to all users. 

FORCE 

NASISIE 

Get rid of a user. 

KILL 

NASISID 

Really get rid of a user. 

SHOTDOBM 

TIME 

Terminate BASIS. 

LIMIT 

TERM,# 

limit NASIS users or resources. 

OSEBS 


List current NASIS users. 

NOSERS 


Ccunt current NASIS users. 

DEBOG 


Enter "debugging" mode. 

NEWS 

*'OEF"|TEXT 

Turn off or add to news text. 

PGMSTOP 

"ON" 1 "CFE” 

Set interrupt stop mode. 

EECOHD 

LEVEI 

Set recording level. 

STAYS "ON"/”OFF« 

Set usage statistics mode. 
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APPENDIX B. - MESSAGE SOBHABY 


The followin<? secticu ccntains a list of all the messaqes in 
the Monitor. There are error iressageSf inf oriBational 
messages and response messages whose formats and meanings 
you should be familiar with. 

CIQ BC=XX 

This is the error message the Monitor issues when it 
receives an invalid return cede from the <TSS) ClEABQ 
function (the actual hexadecimal error code received is XX). 
This indicates a minor failure within TSS itself but the 
Monitor will attempt to continue execution. 

FDQ DVT = XX SDA=(J»KS 

This is the error message the Monitor issues when it 
encounters (from the TSS FINDO function) a terminal type it 
doesn’t know about. The Symbolic Device Address of this 
unknown terminal is displayed in HNNN and the device type 
displayed in XX. The Monitor will attempt to disconnect the 
terminal and forget about it, 

PGM SIR RC=XX 

In attempting to initialize the routine which gets control 
upon the cccurance of a program interrupt (see the PGMSTOP 
command description), the Monitor ran into trouble in the 
TSS SIP functicn. The error code which that function 
returned is displayed in XX. The Monitor will continue 
execution but will not get control when a program interrupt 
occurs. 

RBQ/RDO RC=XX 

This error message is printed whenever the actual attempt to 
write or read one of the user terminals was disallowed by 
TSS. The failure code is displayed in XX and the Monitor 
will attempt to continue execution, pretending that this 
internal failure was an I/O error. 

TS STIHER BC=XX 

In attempting to set the (TSS) timer by which a user is 
time-sliced, an error was encountered in the STIMEH 
function. Since user’s can’t be run successfully without 
time-slicing, the user involved will be logged off by the 
Monitor. The error code found by the Monitor is displayed 
in XX and after logging off the user, the Monitor will 
continue execution. 

TS TTIMEF FC=XX 

This message is issued when the Monitor is unable to CANCEL 
the time-slicing timer for a user. The error return from 
the TTIMES function is displayed in XX and the Monitor 
pretty much just ignores this error. It is not deemed to be 
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erious 

BfiD PHONEtINIB SEA=N^INN 

This message is issued to you when the Monitor detects solid 
I/O errors on one of the user's telephone lines. (Dsually 
this is caused by a user iust hanging up the phone instead 
of logging off normally or by excessive "line noise" on an 
FTS line.) After this message is issued, the user involved 
(if there is one) will be automatically logged off and the 
Monitor will continue execution. The Symbolic Device 
Address of the telephone line causing the error is displayed 
in JJNNN. 

LOGON TKD=XXXX SEA==NKNN OTD=YyYyYYYT 
This message is sent tc vou every time a user logs on to 
WASIS. His "Taskid" (which is just a number equal to the 
number of times somebody has tried to log on during the 
session) is displayed in XXXX, the Symbolic Device Address 
of the user's terminal is displayed in NNNN and the NASISID 
of the user is displayed in YYYYYYYY. This is only an 
informational message. 

LOGOFF OID=YYYYYYYY 

This message is sent to you each time a user logs off of 
NASIS. The NASISID of the user leaving us is displayed in 
YYYXYYYY. (Sometimes a NASISID of "????????" will be 
displayed if the Monitor is unable to determine what the 
NASISID of the user is, for example if he tried to enter a 
NASISID three times and did not come up with one that was 
valid.) This is only an informational message. 

# nSEHS=NNN 

This is the response message to the NDSEHS command. NNN 
merely contains the number of users currently attached to 
NASIS. 

SDN STIMEH HC=XX 

This message is displayed when the Monitor was unable to get 
a timer started for a timed SHUTDOWN. The error code 
returned by the STIHEE function is displayed in XX. The 
Monitor will continue execution but the SHUTDOWN command was 
cancelled. It is suggested that you BCST warning to all the 
user's and then use "SHUTDOWN 0" to shut NASIS down when the 
time comes. 

SHDTDOHN AT BH:FH 

This message is the response to a successful SHUTDOWN 
command and tells you at what time- of-day the system will 
actually terminate. This is only an informational 
message. 

SDN TTIMEH PC=XX 

This error message is displayed when the Monitor is unable 
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to CANCEL the timer which was set for a previous SHUTDOWN 
command. The error cede returned bv the TTIMEF function is 
displayed in XX and the Honitor will continue execution but 
ignore the SHOTEOBN coaisand which caused the error. 

KTPN SIfi fiC=XX 

This error message is displayed when the Monitor is unable 
to initialize the routine it uses to transfer control from 
one user to another. The error code from the SIB function 
is displayed in XX and shortly after it sends this error 
message the Honitor will cause NASIS to terminate 
processing. 

PGM INT VP£V = KXXX?XXXXXXXXXXX TIID= YIYY YY YT 

xxxxxxxx xxxxxxxx xxxxxxxx... 

XXXXYXXX xxxxxxxx xxxxxxxx... 

This is the message displayed when the Monitor detects the 
occurance of a program interrupt. The only thing which will 
concern you in this message is the YYYYYYYY which is the 
NASISID (if any) of the user causing the failure. 

wixi be displayed if there was no NASIS user 
inyolyed.) After this message appears at your terminal^ 
the user will be notified that the system has failed and 
then logged off. See the P6MSTOP command description for a 
further discussion of what the Honitor will do after it 
prints this message. (For those who may be interested, the 
animal before the DID field is the Virtual Program Status 
Word as of the time of the interrupt and the two lines of 
XXXXXXXXs are the users general registers zero through 
fifteen.) 

MSG FROM YYYYYYYY-AAAABBEBCCCCDDEDEEEE... 

This is the message the Monitor prepares for you when one of 
the user's wants to send you a message (with either the user 
MSG or HELP command) » The NASISID of the user sending you 
the message is displayed in YYYYYTYY and the message itself 
is displayed in AAAAEPEE... 

BAD LIMIT COMMAND 

This error message is displayed when you enter one or more 
invalid operands to a LIMIT command. You are referred to 
the discussion of that command for the correct operand 
formats. 

MISSING * 

This error messaae is displayed when you don't follow the 
rules set forth in the first section of this Operator's 
Guide for the entering of Quote marks. What it really 
means is that you have foraotten to a.) pair enclosed quote 
marks or b.) forgotten to surround an operand containing 
quote marks with quote marks. You can. of course, re-read 
the first part cf this Guide, 
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TOO SUCH HEWS 

This error message is displayed when the total number of 
characters in the news text exceeds 4C96* All you can 
really do is either quit making news or delete all the news 
text and start over* The NEWS command which raised this 
error condition is ianored. (See the description of the 
NEWS command.) 

(The last three error messages will be followed by a 7-digit 
**line number” if the error was caused by a line in the 
"NASIS. INITIAL. COHMANCS" dataset. You are advised that the 
command in question is not executed and that you should 
investigate the dataset for errors.) 

BAD COM DS IINE NKNNNNN 

This error message is produced when a line in the 

”NASIS. INITIAL. COMMANES" dataset is discovered to have no 
text (line is too short). The line number of the bad line 
in that dataset is displayed in NNBHNNN and the Monitor will 
ignore this line and trv to read another. 

NASIS TEPWINATING 

This is the informational message which is sent to you by 
the Monitor when it is beginning to terminate NASIS as the 
result of a SHUTDOWN command or a serious error. 

Approximately fifteen seconds after this message is printed, 
the Monitor will relinquish control leaving you in TSS 
command mode once again. (This 15*second pause is so that 
all the users* terminals have time to finish typing whatever 
they are typing.) 

NO MEMOEY-TCTE 

This error message is displayed when the Monitor was unable 
to obtain memory in which to construct a task control table 
for a user who was attempting to log on to NASIS. The user 
will not be logged on and probably quite a few other things 
will start going wrong after you see this message. 

NO HEMORY-ETBI: 

The Monitor was unatle to obtain memory for the user table 
while it was initialixinq itself and is about to give up the 
effort since it will need more memory for other things. The 
Monitor will perform an automatic SHDTDOPN, 

ODIT LOGIC EPR 

This error message is printed when the Monitor's LOGOFF 
routine is called but can find no user to log off. This is 
a programming spaz about which somebody should be notified. 
The Monitor will ignore this error after discovering it. 

NO BEHOFY-NEWS 

The Monitor was unable to obtain memory for the news-text 
buffer. The action for this error is the same as the action 
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for the failure to obtain memory for the user table* The 
Monitor gives up and dies* 

NO NASIS.OSESICS 

The Monitor was unable to locate the dataset containing the 
list of permissible NASISIES to allow onto the system. The 
Monitor will terminate NASIS shortly after this message is 
sent* you should go pound on the Data Base Administrator as 
this message implies scmehody has lost the user list* 

HAD OSERID 

This message is sent when you specify an invalid NASISID to 
a MSG, FOPCE cr Kill command* The Monitor continues 
execution after ignoring the command which caused the 
error. 

NO MSG 

This error message is sent to you after you have entered a 

MSG or BCST command and not specified any message to he 

sent. The Monitor continues execution after ignoring the 
command which caused the error* 

NASIS COMMENCING 

This informational message is sent to you after the Monitor 
has initiali7ed NASIS and is beginning to allow user's 
access to NASIS. It is at this point that NASIS Is 
considered ”up and running**. 

NO HEMOPy-TCT 

This error message is issued if the Monitor is unable to 
obtain memory for the list of connected terminals which it 

must maintain. '^he Monitor recoginzes this as a serious 

error and causes NASIS to terminate after it encounters 
it# 


NO MEMCPY-ATN 

This error message is sent when the Monitor discovers that 
it can't allocate the necessary memory for an attention 
interrupt table for a user. This error probably means that 
bad things are about to happen (because memory is getting 
short) but it ignores the error anyways. It also ignores 
the (user's) attention which caused the discovery of the 
error. 
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TOPIC B. 1 - CONVEPSIONr VftLIIlATION, AND FOBHATTING 
FOOHNES 


I, INTBODtJCTICN 

The design of the NASIS system provides for three types 
of user-vritten icetines to perform special processing 
unique to a particular field. fl ”user” is a mainline 
programmer for the specific data base; such as the data 
base administrator. These routines are classified as 
conversion, validation and formatting. 

The DBPL/I statements used in the NASIS system provide 
for updating and retrieving from a data base. The data 
is always assumed to be character strings. The ability 
to specify Conversion, Validation and formatting 
routines is provided, allow for massaging field data 
and still meet the BBPl/T character string 
requirement. 

The Conversion routine is used to alter character 
string input to any desired form. The Validation 
routine is used either to verify the results of a 
Conversion routine or to verify the character string 
input. 

The Formattinc routine is used to alter the internal 
stored data back tc a character string. 

A. CONVERSION Routine 

The CCNVEFSICN routine is called by the data base 
executive, DEFAC, to convert the data passed by 
the user in a CBPL/I statement from an EBCDIC 
character string to some other type of 
representation for storage on a file. The 
CONVERSION routine is invoked by all DBPL/I 
statements that place data, by field name, onto 
the data base. 

B. VALIDATION Houtine 

The VALIDATION routine is call of theed 
immediately after the call CONVEFSION routine. 
The function of this routine is to verify data 
input for storage on the data base, via the rules 
specified fey the user of this field. A VALIDATION 
routine may be present regardless of the presence 
of a CONVEFSION routine. To assist in this 
evaluation, the NASIS system provides for a 
validation argument. 
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C, FOBMRTTING Boutine 

The TOEMATTING routine is called to change the 
data read fro® the data base into the desirable 
output fora. The FORaftTTING routine is invoked by 
all DEPL/I statements that retrieve data, by field 
name, from the data base* The formatting routine 
specified for a field sill be called whenever the 
data in that field is retrieved* 

A ccllecticn of •’standard” conversion and 
formatting routines is provided in the BDBEXITS 
module (Section IV, Topic B.4)* 

CAItlNG SECUENCE 

In general, these routines are called dynamically, by 
name* They must reside in DBAIIB and be capable of 
accepting a PL/I formatted parameter list. 

A* CCNVEPSIOU Bootine 

The format of the CALI statement used by DBPAC to 
invoke the CCR7EBSI0M routine is as follows: 

CALI rtnname (input-data, output-area, 

error-bit) ; 

where: 

”rtnname” identifies the particular routine 
to be called, as specified in the field 
descriptor. It is the routine’s 
procedure name or an entry point* 

”input-data” is a varying length character 
string, maximum length egual to 4000, 
into which DBPAC has placed the input 
data value* 

”cutput-area" is a varying length character 
string, maximum length egual to 4000, 
initialized to null, into which the exit 
routine places the converted data 
value* 


’’error-tit” is a tit switch, initialized to 
one (1), which is set to zero <0) if 
there were no errors uncovered in the 
conversion, or one (1) if errors were 
detected* The burden of setting the 
switch to zero (0) is with the 
CCKVEBSION routine* 
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B, nLIDATION Soutine 

The fcriiiat of the CSIL statement used by CBPAC to 
invoke the VALIDATION routine is as follows: 

CALL rtnname (input-data, output-area, 

error-tit, arqument) ; 

where: 

"rtnname" identifies the particular routine 
to be called, as specified in the field 
descriptor. It is the routine’s 
procedure name or an entry point. 

’’input-data" is a varying length character 
string, maxiBura length equal to 4000, 
into which DEPAC places the input data 
value after conversion. 

"output-area" is a varying length character 
string^ maximum length equal to 4000, 
initialized to null, into which the exit 
routine places the validated data 
value. 


"error-tit" is a tit switch, initialized to 
one (1) , which is set to zero (0) if 
there were no errors encountered in the 
validation, or one (1> if errors were 
detected. The VALIDATION Routine is 
responsible for setting this switch. 

"argument" is a varying-lenqth character 
strino, maximum length equal to 50, into 
which CBPAC places the validation 
argument, as read from the appropriate 
field of the descriptor for this data 
field. 

C. FOBHAITING Routine 

The format of the CALL statement used by DBPAC to 
invoke the FCFBATTING routine is as follows: 

CALL rtnname (input-data, output-area); 

where; 

"rtnoame" identifies the particular routine 
to be called, as specified in the field 
descriptors. It is the routine’s 
procedure name or an entry point. 
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•’input-data" is a varying length character 
string, fflaximuia length equal to 4000, 
into which DBPAC places the data value 
read from the data base, 

"output-area^* is a varying length character 
string, maximura length equal to 4000, 
initialised to null, into which the exit 
routine places the formatted data 

value. 


Ill, BESIBICTTOhS 

The routines must heed the following restrictions: 

A. The routine can not make any calls to DBPAC (i.e., 
it should not contain any DBPL/I statements) • 

B. The routine is the lowest level module; i.e., it 
does not call any other routines. 

C. The rcutine is written in PL/I* 
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APPENDIX A. 

Diagnostic Hessages an3 Codes Produced By the Conversion, 
Validation, and PoriBattinq Pootines. 

A* Diagnostic Hessaoes 

CALL EBBGS: MODDIE *♦♦♦*♦♦♦ CANNOT BE LOADED. 

This error message is generated if the module named 
cannot he loaded «hen called by DBPAC. Ignoring the 
situation and allcwing the system to run may cause 
unpredictafcle results. 

The most probable reasons for this error are: 

1. failure on the part of the user to have the job 
library containing this program properly DDEFed. 

2. inconsistency between the name of the routine as 
specified in the descriptor file and the name 
actually used when writing the program. 

B. DBPAC Errcr Codes Associated With the Conversion, 
Validation, and Formatting Soutines 

031 KEY FIELD FAILEt CCNVIBSICH. 

The data value passed to the CCNVBESION routine, for 
the hey field of the data base, was found to be in the 
wrong format. 

032 KEY FIEIE FAILED VALIDATION. 

The data value passed to the VALIDATION routine, for 
the key field of the data base, was found to be 
invalid. 

053 DATA FIELD FAILED CCWVEBSIOH. 

The data value passed to the CCNVEESION routine, for a 
data field, was found to be in the wrong format. 

054 DATA FIELD FAILED VALIDATION. 

The diata value passed to the VALIDATION routine, for a 
data field, was found to te invalid. 
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APPENDIX E. 

Sample Validation Boutine 

A sample VAtIDATIOS routine is shown below. The function of 
the routine is tc ccmfare the input data value to each of 
the four byte entries carried in the validation arquments. 
If a match is fcund^ the routine substitutes a numeric code 
for the input data value, resets the error bit to accept the 
field and returns to DBPAC. If no match is found, the 

routine returns to DBPAC with the error bit set to reject 
the field. 


/♦ THIS IS A VAITDATICN BOOTINE POE THE OPEPATICN COTES: ♦/ 

/♦ THE PAEflHETEFS PASSEE ABE: */ 

/♦ A= THE INPUT STSING HHICH IS TO BE VALIDATHE. */ 

/♦ B= THE VALUE TC BE BETUBNED AFTEB VALIDATION. 

/♦ C= THE PIT SWITCH. 'C MEANS PASSED VALIDATION, */ 

/* *1* MEANS FAILED VALIDATION. */ 

/* D= THE VALIDATION ABGUMENTS, ♦/ 

/♦ D IS COMPOSED OF THE FOLLOWING CHARACTER STRING: ♦/ 

/♦ •ADEEADDRCKGEFIDCDEIFDELF* */ 

CHECKOP: PEOCECURE fA,£,C,D); 

DECLARE (A,B,D) CHARACTER(t) VARTING, /♦PARAMETERS. ♦/ 
C BITfl); /♦PARAMETERS. ♦/ 

ON ERROR GO TO 0UT_D1RTY; 

00 I = 1 TO 21 B? 4; 

IF A = STJESTBfE,I,4) 

THEN GO TC 0DT_C1EAN; 

END: 

OUT_DIRTI: /♦ IF IT DOES NOT MATCH KEYWORDS IN ARGUMENT. ♦/ 
C = • 1'F: 

RETURN; 

00T_CLEAN: /* THE VALIDATICN OF CP_CCDE HAS SUCCESSFUL, ♦/ 
C = 'O'E; 

B = A; 

RETURN; 

END CHECKCP; 
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TOPIC B,2 - DBPl/I LANGUAGE EXTENSION USEB’S GUIDE 


I. INTBODDCTICN 

This manual is for PL/I Ptogrammers writing a mainline 
program that accesses a BASIS data base. The data base 
organization heing used is fully specified in the 
**NASIS Overview”. 

All data base access is done by a combination of: 

1. an extension of the FL/I language, called 
CEPL/I, for data base access, 

2. a compilation-time source program processor, 
DB, and 

3. execution-time routines DBPAC and DBLIST, 

This manual is the specification of the DBPI/I 
language extension and is the reference manual to the 
DB preprocessor. Detailed specification of the 
internals of the DB preprocessor are given in Section 
IV, Topic B. 1 of the DWB, and the details on the 
execution-time routines are given in the DEPAC Design 
Specifications (Section iv. Topic B.2 of the DBsi , 
Neither of these t«o sections are needed for writing, 
compiling and executing mainline programs; they may be 
needed for debugging. 

Chapter II of this manual discusses the usage of the 
DB preprocessor. Chapters III through VI are composed 
of discussions and examples of the different features 
of DBPL/I and their interrelationships. Chapter VII, 
”Rules and Syntactic Descriptions”, provides a detailed 
reference to specific information in alphabetical 
order. Appendix A is a quick reference to DBPL/I 
syntax. 

II. THE PREPPOCESSOB 
A. Overview 

DCPI/I language statements have to be processed 
at compilation-time. The processing consists of 
syntax analysis and the generation of PL/I 
statements CAILing DBPAC to accomplish what the 
DBPl/T statements signify. This processing is 
done by the preprocessor stage of the PL/I 
compiler under control of a preprocessor procedure 
named DB. A programmer using DBPL/I does not have 
to write the DB preprocessor or be concerned with 
the PI/I statements that are generated by it; but 
he is reguired to write certain statements in his 
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scarce proqrac so that the DB preprocessor is 
properly invoked by the PL/I compiler for his 
proqtam* He roust also refrain from usinq certain 
identifiers which are reserved words for the DB 
preprocessor *£ exclusive use. 

Osaqe 

The statements required to properly invoke the DB 
preprocessor are illustrated in an exaiiple proqram 
in Fiqure 1. 

1. FIG_1; PPOCEDDPE OPTIONS (HAIN) ; 

2. % IKCIHCE lISEMACfDB)t 

3. CECIABt BEPOBT# CHARACTER (13) VARYING; 

4. 

5. CE (( CN BI!PORPIIF(STAR) GO TO NOTE; )) 

6 . 

7. CE (( 

8. READ FltE(STAB) KEY ( • 67N26508 • ) • 

9. GET FIIE(STAB) FIELD (» BEPTNO* ) INTO (BEPOBT#) ; 

1C. )) 

11. POT DATA (REPCBT#) ; 

12. BETOBN; 

13. 

14. NOTE: POT DATA fSTAR.ONCODE) : 

15. DCNE: DB (( FINISH; )) 

16. END FIG_1; 

% iNCtUDE(DB); 

One %INCL0DE DB statement must he written 
immediately following the external PROCEDDBE 
statement of the compilation. Any PBOCEDORE 
statement attributes could have been used in line 
1. The % INCLODE DB statement must precede all 
other statements such as line 3. 


DB((OF ERBCBEIIE (STAB) GO TO NOTE;)) 


Any EEPL/I statement, such as this ON statement, 
must be written as a subarqument in a DB 
preprocessor function reference. As many DB 
statements may he used as required. Any PI/I 
statements required may be used at lines 3, 4, 6, 
and 11-14. lines 7-10 illustrate that mere than 
one DPPI/I statement may be written in one EB 
statement. However, no non-DBPL/I statements 
would be permitted within a DB function 
reference. 


DB t (FINISH;) ) 
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One tEPL/I FINISH statement mast be written 
following all other C/B statements in the 
compilation. It will asaally be written just 
preceding the EKC statement of the external 
procedure because it generates a HETUEN statement. 
If the statement in line 14 is executed, then the 
procedure will be terminated by control passing 
sequentially to the SEinRN statement generated for 
line 15. The label in line 15 is net reguired, 
but it would be valid as shown {e.g., line 12 
could be; GO TO CONE;). 

The EE preprocessor function generates diagnostic 
comments (see Section III, Topic E. 1 of the 
DNB) ♦ When reviewing a compilation, the 
programmer should first find the summary 
diagnostic message (BB067) to Know how many error 
diaqncstics for which to search. 

C* Reserved Herds 

The FINISH ON-condition is reserved for use by the 
BE preprocessor. The following identifiers are 
reserved for the uses specified in this manual or 
for the BE preprocessor’s use: 

CCLIST 

CPIIST 

EE 

DBEFCBP and all other identifiers beginning 
•DB* 

DOPIIST 

EREOBFTLE 

JtFIEtD 

EEPL/I file-names 

FINISH 

LIST 

fllST 

IISTERR 

CtlST 

UPI.IST 

iIXPEF 

The Pt/I HIGH and NOLL built-in function names mav 
be used as such in the program, but the names must 
not be otherwise declared* 

III. BATA BASE AND ETIES 

A. Overview 

The EBPL/I language provides statements that 
enable data to be transmitted between internal 
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main stotaqe aad external storage devices 
oroanlved as one or more data bases. 

Cata Sets 

Each *’data set” is a named, labelled collection of 
related data, subdivided into keyed data set 
records. 

The one "descriptor data set” for a data base 
stores data describing the information data set(s) 
and their interrelationships. It is a ccllection 
of cne or mote descriptor regions. 

Each "descriptor region" is a collection of 
descriptor records for an information data set. 
The first record in a descriptor region is a data 
set descriptcr record. Subsegnent records in a 
descriptor region are field descriptor records. 

Files 

DBPL/I requires a file name to be used for a file. 
Vhat data set<s) a file name represents is deduced 
from the file title. Characteristics of a file 
may be described with keywords, called file 
attributes, specified for the file name, deduced 
contextually, or assumed by default. 

A "file name" is an identifier specified in the 
PILE clause of DPPL/I statements. A file name may 
not exceed the seven-character lenqth limitation 
for external names. The user must execute a PL/I 
ALLOCATE statement for the FIFCB before executing 
any EBPL/I statements# For example, to use a 
DBPl/1 file-name "plex" the following statement 
must te executed: 

ALLOCATE PLEX; 

Of course the allocation must be done in a program 
in which PLEX will be automatically declared 
because of its use in a DBPL/I statement. If the 
module where the ALLOCATE is to be done does not 
otherwise need DBPl/I statements, the following 
are recommended as a ninisum: 

% INCLUDE LISRMAC(DB); 

ALLOCATE PLEX; 

EEnC» EFEOPFILE(PLEX) SYSTEM;)) 

DBffFINISH;)) 


A "file title" can he specified for a DBPL/I file 
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either through the file name or through the 
character string value of the expression in the 
TITLE option of a DBPL/I OPEN statement. If a 
file is OPENed implicitly, or if no TITLE option 
is specified in the OPEN statement that causes 
explicit opening of the file, the file title is 
assumed to he the same as the file name* 

A file title, not beginning with a pound sign <#> , 
consists of a six-character left-aligned dataplex 
identification and a one-character suffix. Which 
data set(s) the file name represents will he 
deduced from the file title suffix value as 
follows: 

fclank: the identified data base cr anchor 

data set (for physical record 

operations: GET PECOPD or WBITE). 

numeric: the particular associated data 

set* 

Z-Q: the particular subfile data set, 

A-P: the particular index data set, 

A pound sign <#) , prefixed to a file title, 
specifies that a file name represents the 
descriptor region rather than the information data 
set itself, (This combination may be specified 
only in the TITLE option of a DBPL/I OPEN 
statement because it results in an eight-character 
title,) If the eighth character of a descriptor 
region title is blank, the file represents only 
the anchor descriptor region. This facility 
allows mainline programs to create, maintain or 
retrieve from descriptor regions for their own 
purposes. 

File "attributes” for a file name may be 
specified explicitly in a DBPL/I OPEN statement or 
assumed by default. Different attributes may be 
applied in different openings of the same file in 
a prcgraro; at any particular time, the attributes 
applied by the most recent opening apply to the 
file name, 

D. File Level Statements 

DEPL/I provides the OPEN, CLOSE and ON EHHORFILE 
statements for file level operations. All are 
optional; a simple mainline may not need any of 
them. There is no statement for declaring a 
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DBPI/1 file; the DB preprocessor generates the 
necessary Mainline Pile Control Block <HFCB) 
atitomatically • 

The OPEK and CtOSE statements may be used for any 
of the purposes indicated in their descriptions in 
Chapter VII of this manual* 

The OH EBROBFIIB statement is used to establish a 
user's error routine in the mainline to «hich the 
DBPAC execution routines sill return when an error 
condition fe.q** key net found) occurs on a file* 
Several OS statements for a file may be executed 
in a proaram either before or after the file is 
opened « 

An "error routine" mast begin with a statement 
label (the same label identifier specified in an 
ON statement). PL/I (or DEPL/I) statements may be 
written following the label to handle the error* 
These statements may reference certain fields in 
the BFCB for assistance in determining the error 
identity and resuming normal execution. MPCE 
fields are referenced using a qualified name 
censistinq cf the file name and an E1FCB field 
name* The HICB fields that may be referenced in a 
file exception routine are as follows: 

file-name *0)10002 is a binary integer whose 
value specifies the exceptional 
condition. The meanings of the various 
CNCODE values are in Section III, Topic 
B.3 of the DVB. 

file-name. ONEIIE is the current file title. 

file-name. ONFIELD is the current field name 
(when applicable). 

f ile-name.OMEETUKN is a label variable set by 
DBPAC. 

An error routine may be terminated in any manner; 
for certain of the less serious ONCODEs, a GO TO 
f ile-rame.CNBETOBH; statement may be used which 
transfers control to the statement following the 
one that raised the exceptional condition. 

For a more generalized exception routine for one 
or more files, the relevant MFCS fields may be 
referenced using a qualified name consisting of 
the reserved keyword EEFOFFILE and an BFCB field 
name; e.g,, EBROBFILE. OKCODF. 



IV. RECORDS 


fi. Oyerviev 

The data items in a data set are arranged in data 
set records. In this manual, a "physical record" 
means a single data set record having an internal 
self-defining, variable-length format, a 
fixed-length internal hey, and the other data 
items. 

The simple term, "record”, in this manual means 
either a logical record or a physical record, 
depending on content. 

The "current record of a file" is the single 
record having the hey value established by the 
most recent record level operation on the data 
base component file. It is accessible only by 
DBPl/I statements; the mainline has no means of 
addressing it. In a spanned index, the "current 
record" is actually a "region" of one or more 
physical records made to behave like one logical 
record. 

B« Record level Statements 

DBPt/I provides the lOCATE, BE&D, and OKIOCK 
statements for record level operations. The 
record level statements cause a record (possibly 
more than cne physical record) to be transmitted 
between the data set(s) and the current record of 
a file. The transmission may be immediate (READ 
or URIOCK after update) and/or subsequent (LOCATE 
or READ for update) • LOCATE and REAE cause 
automatic file opening, if necessary. 

The tOCATI statement is used to create a new 
current record having a new key for suhseguent 
transmission to the file (no RRITE statement is 
needed) . The LOCATE SOBFILE statement is used to 
create a new current subrecord. 

The READ statement is used to retrieve a record 
from a file and establish it as the current record 
of the file. If the record is updated, it is 
subseguently retransmitted to the file (no REWRITE 
statement is needed) • The READ SUBFILE statement 
is used to retrieve a subrecord and REAL INDEX to 
retrieve an index record. 

The UNLOCK statement releases a locked current 
record so that other tasks can read it. If the 
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reccrfi vas u|:dated, it is retransraitted to the 
file. The DNIOCK SDEFILE statement releases a 
locked current sobrecord. 

C. Physical Record Statements 

DBPI/I provides the GET RECORC and WHITE 
statements for physical records. These are 
special purpose statements intended for use in a 
utility mainline for backing op, restoring or 
reorganizing one particular data set at a time. 
They may be used only by the owner of the data 
base. 

The GET BECCBC moves the current physical record 
without change to the user's receiving field ffor 
backup purposes). 

The WEITE statement transmits a physical record 
from the mainline without change to a data set 
(for restoring or reorganizing purposes). WRITE 
causes automatic file opening, if necessary. 

FIEtDS 

A. Overview 

The data items in a record are arranged in fields 
and, optionally, field elements. 

A ’Afield" is a data item having a field name, an 
internal field descriptor and one or more values 
per record. Since some fields may have multiple 
values per record, an individual data item is 
called a field element. This section of the 
manual relates primarily to anchor, associated and 
sufcrecord fields, although the GET INDEX KEY 
statement may be used for index key fields. 
Facilities for subfile control fields and for the 
list-cf-keys field in index records are discussed 
in Chapter VI of this manual. 

A "field name” is an eight-character string value 
identifying a field. A mainline written in terms 
of a known particular data base may use a 
character-string constant in string quotes. A 
more generalized mainline may use an 
eight-character string variable and assign a value 
to it from input data or from a descriptor record 
before using it as a field name. The names of the 
fields in field descriptor records are given in 
the Descriptor File Specification. 
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An "internal field descriptor" is either a field 
descriptor record in a descriptor reqion ffor data 
base fields) or an internal descriptor <for 
descriptor fields ) • The descriptor record for an 
anchor field may limit GET access of a FIELB to 
those users the file owner has authorized, (PGT 
and BEPtJ'T' may be used only by the file owner) • 

A "field element value" is always a varying length 
character string value in the mainline, 
(Internally, it may be fixed- or variable-length 
and character or coded form,) There may be some 
transformaticn between the internal value and the 
mainline valoe. If the field descriptor names an 
input validation and/or conversion routine or an 
output formatting routine, the relevant routines 
will be invoked automatically when the field is 
accessed. 

The internal value of a field element is null 
until a value is PBT into it, A GET FIELD 
statement retrieves a value even if it is null; a 
null value yields a null mainline string value 
(unless a formatting routine translates a null 
internal value to something non-null such as ’NO 
DATA YET*), To handle such a case, the most 

general way to retrieve field values is as 
fellows: 

EO 1=1 TO HAX(#FIELD(fflfcb,fldname) , 1) ; 

IB { (GET FILE (mfcb) FIELD (fldname) INTO (var) ;) ) 

IF LENGTH (var)=C 

THEN GO TO FIFID_EXBRDSTED ; 

/♦Use field element value in var,*/ 

END; 

FIELD_EXHAOSTED: 

DC not attempt GET FIEID more than #FIELE times or 
something like ’NO DATA YET* will be retrieved 
after values actually present. The mainline may 
determine if the field element is null by testing 
if the length of the mainline string is zero. A 
REPOT statement replaces an element with a new 
value which may be a null value. 

Field Level Statements and Functions 

DBPL/I provides the POT FIEID, GET FIELD and FEPUT 
statements for the creation, retrieval, and 

maintenance cf field elements on anchor and 

subfile records, #FIELD is a PL/I function 
provided for obtaining the numbers of elements in 
a field. The field level statements cause one or 
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more field elements to be transmitted individually 
between the current record of a file and a 
mainline program. A record level statement must 
have teen executed to establish a current record 
of the file before a field level statement may be 
executed. 

The POT FIEIE statement is used to create a new 
field element in the current record of the file. 
It is subsequently transmitted to the file 
automatically (no H5ITE or REHtITE statement is 
needed) • 

The GET FIEIE statement is used to retrieve a 
field element from the current record of the 
file. 

The REPOT statement is used to replace an existing 
primary field element in the current record of the 
file. It is subsequently retransmitted to the 
file automatically (no REWRITE statement is 
needed) * 

The #FIEXC function calculates the number of 
elemerts in a field. It may be used to govern 
GETting of elements or merely to determine if a 
field has any elements or not. 

For a field that may not have multiple elements, 
the field level statements transmit the single 
field element value. 

The following discussion applies to fields that 
may have multiple elements. POTting an element 
appends it to the right end of the field. GETting 
of a FIELD element proceeds from left to right 
and, when the end of the field is passed, null 
values are generated. REPDTting an element 
replaces the "current element of the field" which 
is the element most recently obtained by a GET 
FIELD from the current record of the file. There 
is no facility for referring to an element by its 
position (subscript) in the field. If it is 
necessary to (re)GET an element that is to the 
left of the current element, the record may be 
(re) READ, resetting all of the internal current 
element counters to the first element of the 
fields. If it is necessary to maintain field 
elements in some order depending on their mainline 
values (rather than the order in which they are 
entered) , the following technique may be used (for 
ascending sequence): 
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CECIAPE (0LB,13E1f) CHARACTEE (maxlen) VARYING; 
NEW - expression; 

EE (( READ FILE (name) fpositioning^ ; 
NEXI_EXE»E»t; 

GET FILE (name) FIELD (fieldname) INTO (OLD); 

)); 

IF LENGTH (OLD) /♦ IF OLD IS NON-NDIL ♦/ 
THEN DC; 

IF OLD > HEN /* GREATER THAN*/ 

THEN DO; /♦INSERT ELEMENT */ 

EB ((BEFDT FIXE (name) 

FIELD (fieldname) FROM (HER); )); 
HEN = CID; /♦ FOB PROPAGATION ♦/ 
END; 

GO 1C NEXT_FLEHENT; 

END; 

CB (f POT FILE (name) FIELD (fieldname) FROM 
(NEW); )); 

C. Index Field Retrieval 

DBPl/I provides a special GET INDEX FEY statement 
and the #XREF function for retrieval from index 
records, (Such records may not be explicitly 
created or maintained by mainline programs), A 
READ INDEX statement must have been executed to 
establish a current record of an index before a 
GET INDEX KEY or #XREF may be executed. 

The GET INDEX KEY Statement is used to retrieve 
the index hey field value from the current record 
of the index. 

The #XFEF function calculates the number of cross 
references (anchcr or subfile hey elements) in the 
current record (region) of the index. 

The GET FIELD statement and AFIELD will not work 
on index record fields. An index record RECLEN 
field cannot te retrieved (it doesn*t mean much in 
a spanned index). The GET INDEX KEY statement is 
provided for the index key field, fXREF is 
provided (instead of AFIELD) for the cross 
reference field element count. The GET INDEX LIST 
SET statement (see section VI, B below) retrieves 
the whole cross reference list (instead of an 
element at a time). 


VI, LISTS 


A 


Overview 



PAGE 34 


A of keys is a collection of ascending 

internal key elements in oain storage, identified 
by a mainline list pointer, (The keys are 
accessible only by DBPI/I statements) • 

A ”list pointer” is a FI/I pointer variable 
declared in the mainline, set by a DBPt/I GET SET 
statement or IIST fonction reference, and used to 
identify a list, ft list pointer having the PI/I 
NOLL pointer value identifies a null (empty) 
list. 

There are several ways to form lists (see Figure 
1 ): 

1. Fead anchor records sequentially and pick 
keys, 

2. Bead sutrecords sequentially from a subfile 
and pick keys, 

3. Copy an index record cross reference list. 

4. Copy a subfile control field. 


5. 

Merge 

the 

subfile 

control fields from 

a 


series 

list. 

of 

anchor 

records specified in 

a 

6. 

Merge 

the 

parent 

keys from a series 

of 


sufarecords 

specified 

in a list. 



7. Get keys segnentially from a list and pick 
interesting ones. 


6. Crop the duplicate keys from a list, 

9, Get internal keys sequentially from a list 

and generate internal keys for an output 
list, 

10. logically combine (AND, OF, or AND NOT) 
compatibie lists. 

The number of keys in a list may be found. Key 
elemerts (in external or internal form) may be 
taken from a list. A list may be used to control 
BEADing of anchor records. The mainline may 
request and get control of any errors in the use 
of lists. 

Method 1; forming a list of anchor keys; 
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ptr=HOtI; 

— >DB<(FEAD FIlE(plex) f ile-positioninq; ) ) 
I EB<eGiT FILE(plex) KEY SET{ptr);)) 


the GET KE? SET may or may not le executed 
depending cn the result of GET FIELD statements, 
etc. 

Method 2: forming a list of suhrecord keys; 
ptr=NDlX; 

— >DBf<REAB FIlE(plex) SDEFILE (scfn) 

I file-positioning;) ) 

I DB f (GET FILE (plex) SUBFILE (scfn) 

I KEY SET Cptr) ;) ) 


It is analogous to method 1. 

Method 3; 

tE<(FEAt FILE (plex) INDEX (if n) 
file-positioning;) ) 

CB((GET FILE (plex) INDEX (ifn) 

LIST SETfptrl;)) 

It say be used on any index* 

Method 4: 

CB f (BEAD FILE (plex) file-positioning;) ) 

IE ((GIT FILE (plex) SUBFILE (scfn) LIST 
SET(ptr) ;)) 

It copies the multi-element control field as a 
list of those subreccrds in a subfile that are 
dependent cn a particular anchor record, i.e* a 
”chain^* of related detail records. Note that a 
control field is essentially a stored copy of the 
result of a whole-subfile search for a particular 
parent key value. 

Method 5; 

ptr2=CCLIST (plex, scfn, ptrl) ; 

It is like method 4 repeated for all the keys in a 
Index list with the results all ORed together; It 
produces a Ccxplete Children List* 


Method 6; 
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ptr2=CPLlST (pl€x,ptr1) ; 
cr 

ptr2=opiiST <plex,ptrl) ; 

It reads all the subrecords in a list getting the 
parent key field from each one and merqinq the 
parent keys into the output list. The Unique 
Parent List function drops duplicate parent keys; 
Cotnplete Parent List does not, 

Method 7; 

ptr2=KUll; 

— >CBf(€ET LIST(ptrl) KEY <(n)> ISTO (var) ;H 
I DB((GET lIST(ptrl) KEY SET(ptr2);)) 


Where the GIT KEY SET nay or may not he executed 
depending cn the ’♦var*’ value# Method 7 
essentially handles a special case of method 1 
when the "file-pcsitioninq" would be governed by a 
given list and only the key field would be gotten 
to deterffline selection; for such a case, method 7 
is far more efficient because no record level data 
base I/C is needed. 

Method 8: 

Ptr2 = ULISTJPtrl) ; 

It efficiently produces a new list of unique keys 
(no duplicates) without any record level data base 
I/O, 

Method 9: 

CEUSET IIST(ptr2l SIZE (dim) 

LIKE LIST (ptr1) ;) ) 

>DB((GET IIST(ptrl) INTERNAL KEY 

f INTOlvar);)) 

\ — >DB((P0T LIST(ptr2) INTERNAL KEY 
It FRCH (expr);)l 

\ 


It is a very special purpose variation of method 
7. It works with unconverted external key values. 
If the inner loop is used, it is possible to 
generate more than one key for each GET KEY, 
Since the output list may receive a multiple or a 
fraction of the number of keys in the input list, 
a size dimension must be supplied in the SET LIST 
LIKE IIST statement estimating the minimum number 
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of output Ae^s. 
Method 10: 


ptr3=LIST(ptr ,Ptr2) : 

The LIST function forws a new list in main storage 
frcn two compatible lists in main storage* The 
two argument lists remain accessible for further 
combination or other use. The LIST function is 
used in retrieving for compound gueries. Given 
two lists, A and B, the LIST operations provided 
are illustrated in figure 2, "Venn Diagram." 

When more than two lists have to be combined, the 
mainline mav ose one of the following technignes 
(where B is the resultant intersection list) : 

II = LIST (A, B>; 

T2 = LIST (T1, *$•, C) ; 

EB (( EPEE ITST (T1))); /♦!! DESIBED HEBE*/ 

B * LIST (T2, D); 

DB (( FBEE IIST (T2) )); /*IF DESIBEE BEFE*/ 

A second possible technique is: 


B * LIST 

<Ar 


B) 

F » LIST 

(B, 


C) 

B = IISI 

(B, 


D) 


A third possible techniaoe is: 

B = LIST ( LIST (A, ■&«, B) , IISI (C, 

D)> ; 

The last two techniques do not retain intermediate 
lists. 

List Statements and Functions 

#LIST is a fl/I function provided for obtaining 
the number of keys In a list. For example, if L 
is a pointer identifying a list and S is a 
varying-lenqth character string, the following 
DO-grcup would be valid: 

EO I = 1 TO #IIST fL) ; 

DB << GET LIST (L) KEY INTO (S> ; )); 

BBT SKIP LIST (I, S) ; 

END; 
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If it is merely desired to determine if a list has 
any elements or not, the followinc technique is 
more efficient than a #LIST function reference; 

IF L -.= HOIt THEN /♦ LIST HAS KOBE THAH ONE 
EIEKENT */; 

The GIT LIST KEY statement moves a list element 
key from a list to the user’s receiving string. 
Any conversion from internal to external form is 
done automatically. The GET LIST INTEBNAL KEY 
statement never converts the list element key 
value. 

The READ statement vith the LIST file positioning 
option is used to read the anchor or subfile 
record with the next element of a list as its key. 
It is more efficient than GET LIST KEY; READ by 
KEY because the internal form of the key element 
Is available for use without conversion. 

There are two independent "current elements of a 
list"; the one most recently obtained by a GET 
LIST KEY statement and the one most recently used 
by any HEAD statement under control of the LIST. 
A key may te referred to sequentially forwards or 
backwards or by its position (subscript) in a 
list. The GET or BEAD current element counter may 
be reset by a GET LIST KEY(O) or a READ LIST 
KEY (0) statement respectively. 

The SET LIST, LIKE LIST, and PUT LIST INTERNAL KEY 
statements are for allocating and posting lists 
for special purposes. 

An explicit FREE IIST statement frees the storage 
and NOLLS the pointers for the lists specified. A 
general FREE LIST statement frees all current 
lists but does not NOLL any pointers. 

The ON LISTERFOR Statement is used to establish a 
user’s list exception routine in the mainline to 
which the list processing routines return when an 
exceptional list condition occurs (e.g., 
attempting to combine incompatible lists) • Use of 
the statement is optional and several ON LISTEPROR 
statements may be executed in a program* 

A "list exception routine" must begin with a 
statement label (the same label identifier 
specified in an ON statement) « PL/I (or DBPl/I) 
statements may be written following the label to 
handle the exceptional condition. These 
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stateirents icav reference a binary integer field 
named lIStEBE^ONCCDE ^declared automatically by 
the CE preprocessor) for assistance in determining 
the ercepticcal condition* 

A list exception routine may be terminated in any 
manner; no provision is made for returning to the 
functicn reference that raised the exceptional 
condition* 

yXI. BtllES AKD SYKTACTIC DESCRIPTIONS 

The syntax notation used in this manual is a subset of 

that used in the TSS PL/I Reference Hanoal (For® 

C2fl-2045-0) and specified in Section A thereof, 

1, A notation variable is shovn in loiter case 
letters, hyphens and, possibly, a digit. All such 
variables shovn are defined in this manual either 
syntactically or semantically* 

2, A notation constant denotes the literal occurrence 
of the characters shovn* It consists either of 
all caoital letters or of a special character such 
as a colon, percent sign, parenthesis, comma or 
semicolon, 

3* Braces, O , denote that a choice is to be made* 

4, Corner brackets, <> , denote options, Anything 
enclosed in brackets may appear one time or may 
net appear at all* 

5* The vertical stroke, | , indicates that a choice 
is to be made* 

6* An ellipsis, *•* , denotes that the contents of 
the preceding brackets may optionally occur more 
than once in succession. 
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*The CCIIST function* 

complete Children LIST builds a list of subrecord keys frcni 
a qiven parent key list, for a particular subfile, and 
returns a pointer value identifying the new list to the 
point of invocation* The new list is the complete list of 
dependent subrecords (children) formed by merging the parent 
record's subfile control field lists* Any previously 
current record and sutrecords that were updated will be 
transmitted to the data base. The record identified by the 
last (highest) key in the given list will remain as the 
current (but not locked) record; any current subrecords or 
index records will remain current. The PEAT) cursor of the 
given list will be reset* 

Reference; 

CCLIST (file-name, ctlfield, parent-list-pointer) 

A CCIIST function reference is used as or in an expression; 
it is not to be a subargument in a DB preprocessor function 
reference* The user may not declare any attributes for the 
CCLIST function; the following statement will be generated 
autcmatically: 

DECLARE CCIIST BNTPy ( ,CHAR (6) , FTR) PETORNS (PTB) ; 
Arguments? 

file-name; specifies the data base file from which parent 
records are to be transmitted* It may not be an OUTPUT 
file. If the file is not open, it will be opened 
automatically. The 'file-name* must be used in at least one 
DBPI/I statement elsewfcere in the program. 

ctlfield: is ar expression that specifies the name of the 
subfile control field. The value of the expression is 
converted to a character string, if necessary, the first 
eight characters of which identify the control field. 

parent-list- pointer: must be a pointer expression that 
identifies a list in main storage of parent keys from the 
data base accessed by 'file-name'. It must have been set 
when the CCIIST function is invoked. 

Result; 

The value returned by the CCIIST function is a pointer 
identifying the new complete children list. The new list 
will be in order of ascending internal subrecord key values 
without duplicated values* If none of the parent records 
have any dependent subrecords in the subfile, a MULl pointer 
value will be returned* 
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•The CLOSE Stateioent* 

The CLOSE statement closes a file by disassociating a file 
name from the self-describing data set with which it was 
associated by an OPEN* It may also specify that the file be 
erased* 

General Format: 

CLOSE FILE (file-name) <EPfiSE> <, FILE (file-name) 

<EFSSE»...; 

Syntax Rnlest 

1, The CLOSE statement most be a subargument in a DB 
preprccessor function reference* 

2* Several files can be closed by one CLOSE 

statement* 

General Eules: 

1. A closed file can he reopened* 

2* Closing an unopened file, or an already closed 
file, has no effect unless ERASE is specified* 

3* If a file is not closed by a CIOSE statement, it 
is automatically closed at the completion of the 
proqcam in which it was opened* 

4* If the current record and/or subrecocds were 

LOCATEd or updated, closing will cause them to be 
transmitted to the data base, unlocked (if 
locked) , and disestablished as the current 
record <s) of the file. 

5* The ERASE specification causes the file to be 
erased and uncataXoqued* If the file is a 
descriptor file, the descriptor region is erased* 
If the file is an anchor file, the whole data base 
but net its descriptors is erased. If the file is 
an associated file, a subfile or an index file, it 
is erased independently* ERASE is only valid for 
an OPCATE file. 



PAGE Q2 


*Th€ CPLIST Faitction* 

Complete Parent IIST fcoiias a complete list of parent record 
keys from a given subrecord (children) key list and returns 
a pointer value identifying the nev list to the point of 
invocation. The new list has the same number of parent keys 
as the number of sobtecord ID keys in the given list. 
Parent keys will be repeated if more than one of the given 
subrecord keys are dependent on a particular parent 
record. The sutrecord identified by the last (highest) key 
in the given list will remain as the current (but not 
locked) subrecord of that subfile; any current or index 
records or subtecords cf other subfiles will remain current. 
The READ cursor of the given list will be reset. 

Reference: 

CPLIST (file-name, child-list-pointer) 

A CPLIST function reference is used as or in an expression; 
it is not to be a subargument in a DB preprocessor function 
reference. The user may not declare any attributes for the 
CPLIST function; the following statement will be generated 
automatically: 

DECLARE CPtlST ENTBY(,PTR) RETURNS (PTR) ; 

Arguments: 

file-name: specif ies the data tase file from which subrecords 
are to be transmitted. It may not be an OUTPUT file. If 
the file is not open, it will he opened automatically. The 
file-name must be used in at least one DBPI/I statement 
elsewhere in the program, 

child-list-pointer: must be a pointer expression that 

identifies a list in main storage of subrecord keys from the 
data base accessed by file-name. It must have been set when 
the CPLXST function is’ invoked. 

Result: 

The value returned by the CPLIST function is a pointer 
identifying the new complete parent list. The new list will 
be in order of ascending internal parent key values and may 
have repeated values. If the given subrecord list is null, 
a NULL pointer value will be returned. 
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•Tb€ CB Preprocessor Function* 


DB analyzes a DBPL/I data tase access statement daring 
compilation and generates, in its place, suitable Pl/I 
statements for cotEinnnicatioD with DBPAC. Diagnostic 
comments may also be generated* 

Reference: 

<label:>. . . DE ((«label: subargument > *•*)) 

1* One % INCIODE (DB) preprocessor statement must 
have teen executed ty the PL/T compiler before any 
DB preptocesscr function reference is made in a 
compilation* 

2. Several DB preprocessor function references may be 
made in a compilation* 

3. A DB preprocessor function reference may be made 
only between El/I statements. 

4. When a single DBPL/I statement is to be used as 
the THEN-unit or ElSE-unit of a PI/I IF statement, 
the unit most be a PL/I DO-END group enclosing the 
DB preprocessor function reference* 

5. One or more label prefixes may precede a DB 

preptccessor function reference* They will 
identify the first executable statement generated 
for the first sabargument. 

6. One FINISH statement must be executed by the FI/I 

compiler as the last subargument of the last CB 
preprocessor function reference after all other DB 
preptccesscr function references in a 

compilation* 

Argument: 

1. The argument of a DE preprocessor function 

reference is a character string delimited by 

double enclosing parentheses* Several 

subarguments can appear in the argument. Each 
must be a data base access statement having its 
own terminating semicolon* Blanks and comments 
mav be used freely, as in PL/I, hut no PL/I 
statements are permitted. 

2* One or more label prefixes may precede a 

subargument. They will identify the first 

executable statement generated for the 
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subarquaient 
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•The DUPLIST Function* 


PUPIIST builds, in dynamically allocated main storage# a 
compressed ccpy of a list of keys and returns a pointer 
value identifying the new list to the point of invocation. 

Reference: 

DGPIIST (list-pointer) 

A DOPLIST function reference is used as or in an expression; 
it is not to be a sutargument in a DB preprocessor function 
reference. The user may not declare any attributes for the 
DOPIIST function; the following statement will be generated 
automatically: 

CECLARE DOPIIST ESTBY (PCIRTER) PETORMS (POINTER) ; 


Argument: 

list-pointer; must be a pointer expression that identifies a 
list of )teys in main storage. It must have been set when 
the DOPLIST function is invoked. 

Result : 

The value returned by the DOPLIST function is a pointer 
identifying the compressed list copy. A compressed list has 
none or more list segments of maximum sire followed by the 
last or only list segment allocated to exact length for the 
remaining keys and all segments are exactly filled; thus# it 
occupies the least possible main storage. 



PftGI 46 


•The #FIELD Fucction^ 

#FIELD calculates the number of elements in a field in the 
current record ct subtecord of a file and returns it to the 
point of invocation. 

Reference: 

#FIELD (file-name, field-name) 

fi #EIBLD function reference is used as or in an eirptession; 
it is not to be a subargument in a DB preprocessor function 
reference. The user may not declare any attributes for the 
♦FIELD function: the following statement will be generated 

automatically: 

DECtARE #FIELD EKTRY (, CHARACTER (8)) SEtDRNS (FIXED 
BIN (31) ; 


Arguments: 

file-name: identifies a data base file. It may not be an 
OUTPUT file. A current record or subrecord of the file or 
a subfile must have been established by a DBPI/I READ 
statement when the #FIELD function is executed. Several 
♦FIELD function references may be executed on a current 
(sub) record of a file. 

field-name: is an expression that specifies the name of the 
data base field to be examined. The value of the expression 
is converted to a character string, if necessary, the first 
eight characters of which identify the field. Any field may 
be examined. 

Result: 

The value returned by the ♦FIELD function is a binary 
integer of maximum precision giving the number of elements 
in the field in the current (sub) record of the file. If the 
field has a null value, a rero value will be returned. 
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•Tb€ FINISH Stateaent* 


The FINISH stateroent causes the EF preprocessor to complete 
its analysis of all data base access statements and its 
generation of suitable Pt/I statements. A RET0HN Statement 
will be generated which will terminate erecntion of the 
procedure. Diagnostic comments may also be generated. 

General Format: 

FINISH; 

Syntax Pule: 

One FINISH statement most be used after all other data 
base access statements in a compilation. It must be 
the last subargument in a DB preprocessor function 
reference. 
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•The FREE LIST Statement* 

The FREE LIST statement frees main storage previously 
dynamically-allccated for one or more lists of 
(cross-reference) keys. 

General Format: 

FREE LIST <(list-Fclnter<,list-pointer> 

Syntax Rules: 

1. The FREE LIST statement must be a subargnment in a 
DB preprocessor function reference. 

2. Several lists may be explicitly freed by one FREE 
LIST statement. 

General Rules: 

1. If a list-pointer is explicitly specified, it oust 
be a pointer expression that identifies a list of 
keys in main storage. It most have been set when 
the TREE LIST statement is executed. 

a. If the value of the list-pointer is NULL, no 
action will be taken for that list pointer. 

b. If the value of the list-pointer is not MULL, 
the dynamic main storage for the list of keys 
identified by it will be freed and the 
list-pointer will be given a SELL pointer 
value. 

2. If no list-pointer is explicitly specified in the 
FREE LIST statement, all dynamic list storage will 
be freed. The user’s list pointers are not given 
NOIL values; it is the user’s responsibility not 
to use them for list identification until they are 
reset. If no dynamic list storage has been 
previously allocated. this option of the FREE 
LIST statement will have no effect. 
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•The GET EIEiD Statement* 

The GET EIELD Statement moves a data element value from the 
current record or subrecord of a file to the user’s 
receiving field; it may cause the value to be converted from 
an internal forir to a display form. 

General Eocmat; 

GET THE (file-name) flJLE (field-name <, field-naaie> ) 

TRTC (variable <, variable 2 ••• ); 


Syntax Sules: 

1. The GET FIEIC statement must be subarqument in a 
EE preorocesscr function reference. 

2. Several data element values can be moved by one 
GET FIEtD statement. In this ^ case, a 
corresDondinq variable must be specified for each 
field name. 

General Buies: 

1. The data element value vill be taken from the data 
base file specified in the FIIE clause. It may 
not be an ODTPUT file, 

2. A current record or subrecord of the file or a 
subfile must have been established by a READ 
statement vhen the GET statement is executed. 
Several GET FIEID statements may be executed on a 
current (sub) record of the file* 

3. The field-name is an expression that specifies the 
name of the data base field from which the data 
element value is to be obtained. The value of the 
expression is converted to a character string, if 
necessary, the first eiqht characters of which 
identify the field. If the user who executes the 
GET FIELD statement is not the owner of the file, 
the field-name may not specify a field that the 
owner has not authorized the user to GET. 

a. If the field is not subdivided into elements, 
the data element value (possibly null) will 
te taken from the field in the current record 
cf the file. 

b. If the field is a multiple-element field, the 
data element value will be taken from the 
next element of the field, in left to riuht 
order, following the element taken by the 
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freyioas GET of the FIELD of the carrent 
record of the file* If there has been no 
previous GET of the FIELD since the record 
vas BEAD, the leftmost element is taken 
unless the field is null, in which case, a 
null element value vill be generated. If a 
previous GET of a FIELD since the record was 
READ tock the last (rightmost) element, a 
null value will be generated. 

4. The variable in the INTO clause specifies the 
user's receiving field. It must he the identifier 
of a varying length character string variable 
declared by the user. The internal form of the 
data element value will be taken as a varying 
length character string (of zero length, if the 
value is null), converted to display form and 
assigned to the variable. If the length of the 
display form of the value exceeds the 
user-declared maxinum length of the variable, the 
value will be truncated and an error condition 
raised. 
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•The GET INEIX KEY Statement* 


The GET INDEX KEY statemeiit moves the key value from the 
current record cf an index to the user's receiving field; it 
may cause the value to fce converted from an internal form to 
a display form* 

General Format: 

GET FILE ffile-name) INDEX (indfield) KEY INTO (variable); 
Syntax Rule; 

The GET INDEX KEY Statement must be a subargument in a 

DB preprccessor function reference. 

General Rules: 

1. The FILE clause specifies the data base file from 
which an index key value is to be taken. It may 
not he an OUTPUT file. 

2» The INDEX clause specifies the index file from 
which the current index key value is to he taken* 
The indfield expression value is converted to a 
character string, if necessary, the first eight 
characters of which identify the Indexed fields 

3. A current record of the index must have been 

established by a FEAD INDEX statement when the 
GET INDEX KEY statement is executed* 

4* The variable in the INTO clause specifies the 

user's receiving field* It must be the identifier 

of a varying length character string variable 
declared by the user* The internal form of the 
index key value will be taken as a varying length 
character string, converted to display form and 
assigned to the variable* If the length of the 
display form of the value exceeds the 

user-declared maximum length of the variable, the 
value will be truncated and an error condition 
raised* 
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•The GET KEY SET Statement* 


The GET KEY SET statement moves the internal key value from 
a current record or subiecord of a file to a list of keys in 
dynamically allocated main storage and sets a pointer 
identifying the list or extends an existent list. 

General Format: 

GET FIIE (file-name) <STJEFILE (ctlfield) > KEY SET 

(list-pointer) ; 

Syntax Buie: 

The GET FE? SET statement must be a subarqument in a CB 

preprocessor function reference* 

General Gules: 

1* The FTIE clause specifies the data base file from 
which a key value is to be taken* It may not be 
an OUTPUT file* 

2a. If no SOEFIlE clause is present, the internal key 
value vill be taken from the current root 
record * 

b« A SOEEILE clause specifies that the internal key 
value from a current subrecord is to be taken* 
The ctlfield expression value is converted to a 
character strinq, if necessary, the first eight 
characters of which identify the control field. 

3. A current (sub) record must have been established 
by a PIAD or GEAU SUBFILE statement when the GET 
KEY SET statement is executed. 

4* The list-pointer in the SET clause specifies the 
user’s pointer identifying the list of keys in 
main storage. It must be the identifier of a 
pointer variable declared by the user* 

4a. If the user assigns the NULL value to his 
list-pointer before executing the GET KEY SET 
statement, main storage will be dynamically 
allocated automatically for a new list, the key 
value will fce moved there from the current 
(sub) record, and the list-pointer value will be 
set to identify the list in main storage. The 
list remains allocated in main storage until the 
user executes a FPEE LIST statement. 
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Otherwise, tfce list-pointer should identify a list 
of keys in main storage to which another 
compatible key value is to be appended. It must 
have been set (by the user assigning NULL and 
executing a GET KEY SET statement as described 
above) when this GET KEY SET statement is 
executed. Tte key value will be moved from the 
current (sub) record. The list-pointer will be 
unchanged. 
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•The GET LIST INTEBUAl KEY INTO Statement* 

The GET LIST INTEFNRL KEY INTO Statement increments the 
internal GET cursor of a list of Keys in main storage 
identified by a list pointer and moves the indicated kev 
valae in internal form to the user's receiving field. 

General Formatr 

GET LIST (list pointer) INTEPNAl KEY INTO (variable); 
Syntax Buie: 

The GET LIST INTE0NA1 KEY INTO statement must be a 

subargument in a LB preprocessor function reference. 

General Pules: 

1, The list-pointer must be a pointer expression that 
identifies a list of keys in main storage from 
which the next key value is to be taken. It must 
have teen set when the GET LIST IN^pEBNAL KEY INTO 
statement is executed. In the exceptional case of 
a list pointer having a NULL pointer value, a null 
string value will be generated. 

2, The internal GET cursor of the list will be 

incremented to indicate that the next element of 
the list, in order of ascending internal key 
values, is current and will be taken* (If the 
internal GET cursor was reset, the element having 
the Icwest internal key value is current and will 
be taken. If the internal GET cursor was on the 

last element (highest internal key value) , the 

cursor will te reset and a null string value will 
be generated,) 

3, The variable in the INTO clause specifies the 

user's receiving field. It most be the identifier 
of a varying length character string variable 
declared by the user. The internal form of the 
key value will be taken as a varying length 
character string (cf zero length on end of list) 
and assianed without formatting to the variable. 

If the length of the internal form of the value 

exceeds the user-declared maximum length of the 
variable, the value will be truncated and an error 
condition raised. 
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•The GET LIST KEI (0) Statement* 

The GET LIST KET (0) statement resets the internal GET cursor 

of a list of keys in main storage. 

General Format; 

GET LIST f list-pointer) KEY(O); 

Syntax Buie: 

The GET LIST KEY(O) statement most be a subargument in 

a D6 preprocessor function reference. 

General Buies: 

1. The list-pointer must be a pointer expression that 
identifies a list of keys in main storage whose 
GET cursor is to be reset. The list-pointer roust 
have been set when the GET LIST KEY(O) statement 
Is executed. In the exceptional case of a 
list-pointer hawing a NOLL pointer value, no 
action will occur and no error condition will be 
raised. 

2. The internal GET cursor of the list will be reset 
(as it was when the list was built) * 
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*Th€ GET LIST KEY INTC Statement* 

The GET LIST KEY IMIO statement increments or sets the 
internal GET curscr of a list of Keys in main storage 
identified by a list pointer and moves the indicated key 
value to the user's receiving field; it may cause the value 
to he converted from internal to display form* 

General Format: 

GET IIST (list-pointer) KEY <(rel-key)> INTO (variable); 
Syntax Buie; 

The GET LIST KEY INTO statement must be a subargument 

in a DB preprocessor function reference* 

General Buies: 

1. The list-pointer must he a pointer expression that 
identifies a list of keys in main storage from 
which the key value is to be taken* It must have 
been set when the GET LIST KEY INTO statement is 
executed. In the exceptional case of a list 
pointer having a HULL pointer value^ a null string 
value will fee generated* 

2a* If nc rel-key is specified, the internal GET 
cursor of the list will be incremented to indicate 
that the next element of the list, in order of 
ascending Internal key values, is current and will 
be taken* (If the internal GET cursor was reset, 
the element having the lowest internal key value 
is current and will be taken. If the internal GET 
cursor was cn the last element the cursor will be 
reset and a null string value will be generated,)^ 

b. If a rel-key expression is soecified, its valde 
will be converted, if necessary, to a fixed binary 
integer of maximum precision. 

If rel-key has a negative value, such as -1, the 
internal GET cursor of the list will be 
decremented to indicate that the previous element 
of the list, in order of internal key values, is 
current and will he taken. (If the internal GET 
cursor was reset, the element having the highest 
internal key value is current and will be taken. 
If the internal GET cursor was on the first 
element, the curscr will be reset and a null 
string value will be generated.) 

If rel-key has a positive value, the internal GET 
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cursor oif the list vill be set to indicate that 
rel-key the relative element of the^ list is 
current and vill be taken* (If rel-key is zero or 
qreater than the nninter of keys in the list^ the 
cursor will be reset and a null strinq value will 
be generated*) 

The variable in the IHTO clause specifies the 
user^s receiving field* It must be the identifier 
of a varying length character string variable 
declared by the user* The internal form of the 
key value will be taken as a varying length 
character string converted to display form and 
assigned to the variable. If the length of the 
display form of the value exceeds the 
user-declared maximum length of the variable, the 
value will be truncated and an error condition 
raised* 
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’The GET LIST KEY SET Statement* 

The GET LIST KEY SET statement moves the current internal 
key value from a list cf keys identified by a list pointer 
to a new list in dynamically allocated main storage and sets 
a pointer identifying the new list or extends an existent 
list. 

General Format: 

GET LIST <list-pcinter) KEY SET (nex-list-pointer) ; 
Syntax Rule: 

The GET LIST KEY SET statement must be a subargument in 

a DB preprccessot function reference* 

General Rules: 

1. The list-pointer must be a pointer expression that 
identifies a list of keys in main storage having a 
non-7€to GET cursor indicating a current key, 

2. The internal key value will be taken from the 

current element of the list indicated by the 

internal GET cursor. The GET cursor will be 

unchanged, 

3. The new-list-pointer in the SET clause specifies 
the user’s pointer identifyinq the new list of 
keys in main storage. It must be the identifier 
of a pointer variable declared by the user, 

3a, If the user assigns the NULL value to his 

new-list-pointer before executing the GET LIST KEY 
SET statement, main storage will be dynamically 
allocated antcmatically for a new list, the key 
value will be moved there, and the 
new-list-pointer value will be set to identify the 
new list in main storage. The new list remains 
allocated in main storage until the user executes 
a FREE IIST statement, 

3b, Otherwise, the new-list-pointer should identify a 
list of keys in main storage to which another 
compatible key value Is to be appended. It must 
have been set when this GET LIST KEY SET 

statement is executed. The key value will be 
moved and the new-list-pointer will be 
unchanged* 
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*Th€ GET LIST SIT Stat€iBent« 

The GET LIST SET stateaent moves a list of keys from the 
current record cf an index or fro® a subfile control field 
in the current root record to dynamically allocated main 
storage and sets a pointer identifying it. 

General Format: 

GET FILE (filename) <ISEIX <indf ield) >LIST SET (list-pointer) 

<SDEFILE (ctlf ield) > 


Syntax Fule: 

The GET LIST SET statement must be a sabargument in a 

CE preprocessor function reference. 

General Rules: 

1. the FILE clause specifies the data fcase file from 
which the list of keys is tc be taken. It may not 
be an onTFtJT file. 

2a. If an INDEX clause is specified, a current index 
tecctd must have been established by a READ INDEX 
statement when the GET INDEX LIST SET statement is 
executed. The INDEX clause specifies the index 
file from which the list of (cross-reference) kevs 
is to be taken. The indfield expression value is 
converted to a character string, if necessary, the 
first eight characters of which identify the 

indexed field. 

2b. If a SUEFIIE clause is specified, a current root 
record must have been established by a BEAD 

statement when the GFT LIST SET statement is 

executed. The ctlfield expression value is 
converted to a character string, if necessary, the 
first eight characters of which identify the 

contrcl field from which the list of keys 

(children) is to be taken. If the user who 
executes the GET SOBFIIE LIST SET statement is not 
the owner of the file, the ctlfield may not 

specify a ccntrol field that the owner has not 

authorized the user tc GET. 

2c. If neither an INDEX nor a SDBFILE clause is 

specified, the FILE must be an INPDT file opened 
with a TITLE for independent access to a 
particular inverted index file and a current 
record must have been established by a BEAD 

statement when the GET LIST SET statement is 
executed. Tie list of (crcss-reference) keys will 
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be taben* 


The list-pcinter in the SET danse specities the 
user's pointer to fce set to identify the Ixst of 
kevs in main storage. It must be the identifier 
of 'a pointer variable declared by the user. 


a If the list of keys field of the current 
record is noll^ the list-pointer will be 
given a KOll pointer value. (This occurs for 
the SUBEILE case when the control field is 
null indicating no subordinate (children) 
subrecotds. ) 


b. Otherwise, main storage will be dynamically 
allocated automatically for the list, the 
list of keys will be moved there from the 
current record, and the list-pointer value 
will be set to identify the list in main 
storage. The list remains allocated in main 
storage until the user executes a FREE IIST 
statement. 
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•The GET RECORD Statement* 

The GET RECORD statement moves a physical record in internal 
form from the current record of a file to the user's 
receiving field. 

General Formats 

GET FILE <file-name> RECORD INTO (variable) ; 

Syntax Rule: 

The GET RECORD statement must be a subargument in a DB 

preprocessor function reference. 

General Pules: 

1. The physical record vill be taken from the current 
record of the file specified in the FILE clause. 
It must be an OPCATE or INPDT file ovned by the 
user who executes the GET BECORD statement. 

2. A current record of the file must have teen 
established fcy a READ statement when the GET 
statement is executed. Several GIT statements may 
be executed cn a current record of the file* 

3. The variable in the INTO clause specifies the 
user's receiving field. It must be the identifier 
of a structure or fixed-length character string 
variable declared by the user. The internal 
self-defining physical record -will be moved into 
the variable without any conversion. No receiving 
field length checking vill be done* (A GET FIELD 
•RECIEN* statement may be used for this purpose.) 
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•The % INCLUDE lISBdAC (DB) Preprocessor Statement’ 

The % INCLUDE LISPWAC (DB) preprocessor statement causes the 
text of the DB preprocessor function to be tauten from the 
system source library durinq compilationr incorporated in 
the source proqtan and activated. 

General Format: 

% INCLUDE IISEWAC <DB) ; 

Syntax Pule: 

Only one % IHCIOEI CB preprocessor statement may be 
used in the source text for a compilation. It must 
immediately follow the beginning PHOCEDUHE statement, 
before any other statements, if the compilation 
contains DB preprocessor function references for data 
base access statements. 
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'The LIST Function* 

LIST derives a new list of (cross-reference) keys from two 
given lists of keys and returns a pointer value identifyinq 
the new list to the pcint of invocation. The new list may 
be the union or intersection of the given lists or the 
sublist of the first given list excluding the second. 

Reference; 

LIST (list-pointer-1, operator, list-pointer-2) 

A LIST function reference is used as or in an expression; it 
is not to be a subargument in a DB preprocessor function 
reference. The user may not declare any attributes for the 
LIST function; the following statement will he generated 
automatically: 

DECLARE LIST EKTBI (POINTER, CHARACTER ( 1) , POINTER) 
RETORKS (POINTER) ; 


Arguments: 

Each of the tvc list-pointer arguments must be a pointer 
expression that identifies a list of keys in main storage. 
Each must have been set when the LIST function is invoked. 
The lists of keys identified must be compatible (havina the 
same internal key element length, etc.). 

The operator argument is an expression that specifies the 
list operation to derive the new list. The value of the 
operator will be converted, if necessary, to a one-character 
string. The value must be; 

logical OR, *,*, specifying the union, 

logical ANC, *G*, soecifying the intersection, or 

minus sign, specifying the sublist of the first 

list excluding the second list. 

Result; 

The value returned by the LIST function is a pointer 
identifying the new list. The new list will be in order of 
ascending internal key values without duplicated key values 
(unless there are duplicates in one of the argument lists) . 
If the new list is null, the value returned may be assigned 
to one of the argument list pointers; however, the argument 
list would then be lost to the mainline (unless the user had 
assigned its pointer value to another pointer previously) 
and could not be explicitly freed (but FREE LIST; would free 
it and all other lists). 
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•Th€ #LIST Ftinction* 

#LIST calculates the number of fcross-reference) keys in a 
list of keys identified by a list pointer and returns it to 
the point of invccaticn* 

Beference: 

#1IST flist-pointer) 

A #LIST function reference is used as or in an expression; 
it is not to be a suharqument in a DB preprocessor function 
reference. The user may not declare any attributes for the 
#iIST function; the following statement will fee generated 
automatically; 

DECLARE #LIST ENTBtl (POINTER) RETURNS (FIXED 
BINAPY(31) ) ; 

Argument : 

The list-pointer argument must be a pointer expression that 
identifies a list of keys in main storage. It must have 
been set when the #tIST function is invoked. 

Result; 

The value returned by the dllST function is a binary integer 
of maxitnum precision giving the namber of keys in the list 
identified by the list-pointer argument. If the 

list-pointer has a HULL pointer valuer a zero value will be 
returned. 
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•The LOCATE Statement* 

The locate statement, which applies to OOTPOT or DIRECT 
UPDATE files, canses formation of a new current record 
having a hey field and having all other fields null; it may 
also cause tr anstnissicn of the previously current record to 
the data base. 

General Format: 

LOCATE FIIE (file-name) KEYFPOM (expression) ; 

Syntax Rule; 

The LOCATE statement must be a subargument in DB 

preprocessor function reference. 

General Pules: 

1. The FILE clause specifies the data base file to 

which the record is to be subsequently 

transmitted. It must be owned by the user who 
executes the lOCATE statement. It may not be an 
INPOT or SEQUENTIAL UPDATE file, 

2. If the file is not open, it is opened 

automatically. 

3. The value of the expression in the KEYFROB clause 
is converted to a varying length character string, 
if necessary, validated and/or converted to an 
internal form. 

a. If the file has the SEQUENTIAL OUTPUT 

attributes, the internal key is checked for 
ascending sequence and subsequently used as 
the key of the record when it is transmitted 
to the data base. 

b. If the file has the DIRECT attribute, a READ 
FEY is attempted using the internal key. If 
the key is found, a duplicate key error 
condition is raised and the LOCATE statement 
has the effect of the READ KEY statement. If 
the key is not found, it is subsequently used 
as the key of the record when it is 
transmitted to the data base, 

4. After execution of the LOCATE statement, 
subtecords nay be LOCATEd and values may be PUT 
into fields (ether than the key) of the record for 
subsequent transmission to the data base, which 
will occur immediately before the next LOCATE, 
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READ, CIOSE or automatic close operation on the 
file. 
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•The LOCATE SUBFILE Statement* 

The LOCATE SUBFILE statement causes formation of a new 
current subrecord bavinq a frey field and a parent keyfield 
and havinq all ether fields null; it also causes the new key 
to be automatically entered in the parent record control 
field; it may also cause transmission of the previously 
current subrecord of the subfile* 

General Format: 

LOCATE PILE (file-name) SOEFILE (ctlfield) ; 

Syntax Pule: 

The LOCATE SUBFILE statement must be a subarqument in a 

DB preprocessor function reference. 

General Pules: 

1* The FILE clause specifies the data base file to 
which the subrecotd is to be subsequently 
transmitted. It must be owned by the user who 
executes the LOCATE SUBFILE statement. It may 
not be an IPfUT file. 

2, A current record of the file must have been 
established when the LOCATE SUBFILE statement is 
executed. Several LOCATE SUBFILE statements for 
one or more subfiles may be executed cn a current 
record of the file. 

3, The ctlfield is an expression that specifies the 
name of the subfile control field. The value of 
the expression is converted to a character strinq, 
if necessary, the first eight characters of which 
identifv the control field, 

4, After execution of the LOCATE SUBFILE statement, 
values may be POT into fields of the subrecord for 
subseguent transmission to the data base, which 
will occur immediately before the next LOCATE 
SUBFIIE or BEAD SDBFIIE on this subfile or before 
the next CLOSE or automatic close on the file. 
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•The ON Statement* 

The ON statement specifies what action is to be taken when 
an interruption results from the occurrence of the specified 
error condition* 

General Format: 

ON <EFBORFItE (file-name) > <SYSTF« > ; 

<LISTEFHOR > <G0 TO label> 

Syntax Rule: 

The ON statement most be a sobargument in a OB 

preprocesscr function reference. 

General Rules: 

1. The OH statement determines how an error occurring 
for the specified condition is to be handled* 
Whether the error is handled in the standard DB 
fashicn or by a user-supplied method is determined 
by the action specification in the ON statement, 
as follows; 

a. If the action specification is SYSTEH, the 

standard CE action is taken. For most 

conditions, the system simply posts the 
CNCODE field and raises the ERROR condition* 
(Note that the standard DB action is always 
taken if an interruption occurs and no ON 
statement for the condition is in effect.) 

b. If the action specification is GO TO, the 
user has supplied his own error-handling 
action at label. Control Is not transferred 
to label when the ON statement is executed; 
ccntrcl is transferred only when an error 
results from the occurrence of the specified 
condition* 

2. The action specification established by executing 
an OK statement remains in effect unless it is 
over-ridden by the execution of another ON 
statement specifying an action for the same 
condition* 
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»Tfee OPEN Statenient* 

Th€ OPEN statement opens a file by associating a file naae 
with a DATA BASE, It may also specify attributes for the 
file. 

General Forioat: 

OPEN FILE (file-name) <TIT1E (expression) > <access> 

<f unction> 

<, FILE (file-name) <TITIE (expression) > <access> 

<f unction>>. • • ; 

where "access** ist 
DIRECT ! SEOOERTIAt 

and "function" is: 

INPUT I onTPOT I UPDATE 

Syntax Rules: 

1* The OPEN statement must be a sobargument in a DB 
preprccesscr function reference. 

2* Several files can be opened by one OPEN 

statement. 

General Rules: 

1. If a file is not opened by an OPEN statement, it 
is autOBiatically opened when a READ or LOCATE 
statement for the file is first executed. 

2. Opening an already opened file by an OPEN 

statement causes it to be closed and reopened. 

3. If the TITLE cptioD is specified, the value of the 
expression is converted to a character string the 
first eight characters of which identify the data 
base to be associated with the file. If the TITLE 
option is net specified, the file-name is taAen 
to identify the data base* 

4. If no access attribute is specified, DIRECT is the 
default unless a NBITE statement on the file is 
used in the same compilation, thus implying the 
SEQUENTIAL attribute. 

5* If a function attribute is specified, it 
determines the direction of data transmission 
permitted for the file. If no function attribute 
is specified, it is implied from the usage of 
other data base statements on the same file in the 
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coippilaticn (e.g., BEP0T implies UPDATE), If no 
other data base statements on the same file appear 
in the compilation, the default is IHPOT. The 
only user permitted to access and OUTPUT or UPDATE 
file is the ovner of that file. 



PAGE 71 


•The PUT FIELD Statement* 

The PUT FIELD statement moves a 6ata element valne to the 
current record or sotrecord of a file for subsequent 
transmission to the data base; it may cause the value to be 
validated and/cr ccnveited to an internal form and it may 
also cause a cross-reference to be automatically entered In 
an index file* 

General Format: 

PUT FILE (file-name) FIELD (f ield-name<, field-name> ...) 

FPOn (expressionC, expression> •••); 


Syntax Rules: 

1. The PCT FIELD statement most be a subargument in a 
DE preprocessor function reference, 'The READ 
Statement* 

2. Several data element values can be moved by one 
POT FIEID statement* In this case, a 
corresponding expression must be specified for 
each field-name* 

General Pules; 

1* The FILE clause specifies the data base file to 
which the data element value is to be subsequently 
transmitted* It must be an OUTPUT or UPDATE file 
owned by the user who executes the POT statement* 
It may not be an associated file or an Index 
file. 

2* A current exclusive record or subrecocd (depending 
on the field-name) of the file or subfile must 
have been established when the PUT statement is 
executed. Several PUT statements may be executed 
on a current exclusive (sob) record of the file. 

3* The field-name is an expression that specifies the 
name of the data base field into which the data 
element value is to be moved. The value of the 
expression is converted to a character string the 
first eight characters of which identify the 
field. The field-name may not specify the key 
field of the record or any other read only field. 
The POT statement moves a value to a field element 
that had no previous value, 

a. If the field is not subdivided into elements, 
it must have had a null value before the PUT 
statement is executed to give it a value* 



b. If the field is a multiple-element field, a 
new element will be added at the right end of 
the field. 

The expression in the FFOH clause specifies the 
data value to he given to the field element. The 
value of the expression is converted to a varying 
length character string, if necessary, validated 
and/or converted to an internal form and moved 
into the current record of the file. (If the data 
base field element is variable-length, other 
fields are automatically shifted to make room.) 
The varying length character string value after 
any conversion to an internal form must have a 
length greater than rero; i.e. , a null string is 
an invalid data value for a POT statement. 

If the data base field has an inverted index file, 
a cross-reference of the internal data element 
value to tie key of the (sub) record sill be 
automatically entered in the inverted index 
file. 

The (sub) record with the new data element value 
will be transmitted to the data base when an 
nmoCK statement for the (sub) file is executed or 
iBoediately before the next LOCATE or BEAt on the 
(sub) file or immediately before the next CLOSE or 
automatic close operation on the file. 
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•The PUT LIST INTESNAI KEY TROH Statement* 

The POT LIST INTEPKAI KEY FROM statement moves an internal 

key value to extend a list of keys in main storage. 

General Format: 

POT LIST (list-pointer) INTERNAL KEY FROM (expression 

<,expression>, ; 

Syntax Rules: 

1, The POT LIST INTEtiNAI KEY FROM statement must fee a 
subarqument in a DB preprocessor function 
reference. 

2. Several internal Key values can be moved by one 
POT LIST INTEHNAI KEY FBOB statement. 

General Rules: 

1, The list-pointer in the LIST clause specifies the 
user's pointer identifying the list of keys in 
main storage to vhich the internal key value is to 
be moved. It must have been set when the PUT LIST 
INTERNAL KEY FROM statement is executed. In the 
case of a list pointer having a NOLL pointer 
value, a list error condition will be raised. 

2. The expression in the FROM clause specifies the 
internal key value to be moved to the list. The 
value of the expression is converted to a varying 
length character string which must be the same 
length as the list element size. If the length is 
different or zero (null) an error condition will 
be raised. 
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•The EEAC Statement* 

The BEAD statement canses a parent record or a snbrecord to 
be transmitted from the data base and established as the 
current record of the file (or as the current subrecord of 
a subfile); it may also cause transmission of the previously 
current record (or sufcrecord of a subfile) to the data 
base. 

*Hhen BEADinq accordinq to a LIST of subrecord ID keys. 
General format: 

READ FILE (file-name) <f ile-positioninq> <BOLOCK>; 
where f ile-positioninq may be: 

BACKWARDS \ KET (expression) | 

LIST (list-pointer) <KEY (r€l-k€y)> I 
PER SDBFIIE (Ctlfield) 

Syntax Rule: 

The BEAD statement must be a subargument in a EB 

preprocessor function reference. 

General Buies: 

1. The FILE clause specifies the data base file from 
which the record is to be transmitted. It may not 
be an ODTPDT file. 

2. If the file is not open, it will be opened 
automatically unless BACKWAHDS or PEB SOBFItE is 
specified* 

3a. If nc file positioning option is specified, the 
next sequential record , following the one 
previously read, will be transmitted. If the file 
is newly opened, the record having the lowest 
internal key value will be transmitted. 

b. If the BACKWARDS f ile-positioninq option is 
specified, the previous sequential record, in the 
order of internal key values, preceding the one 
previously read will be transmitted. If the file 
is newly opened, a file positioning error 
condition will be raised. 

c. If the KEY file-positioning option is specified, 
the value of the expression will be converted to a 
varying length character string, validated and/or 
converted to an internal form and used to 
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determine which record will be transmitted* If 
the key cannot be found, a key error condition 
will be raised, but the record havinq the next 
lower internal key value will be transmitted# 

If the tIST file-positioning option is specified, 
the file may not be an index file# The 
list-pointer must be a pointer expression that 
identifies a list of anchor or subrecord keys in 
main storage to control the BEAPing# It most have 
been set when the PEAD statement is executed* 
The keys in the file list identified must be 
compatible with the internal anchor keys of the 
file, or witfc the subrecord keys of one of its 
subfiles. In the latter case the list determines 
which subfile will be accessed for a subrecord to 
be made current# In the case of a list-pointer 
having a KOLl pointer value, a key error condition 
will be raised and no record will be 
transmitted. 

If the LIST clause is not followed bv a KEY 
clause, the internal BEAD cursor of the list will 
be incremented to indicate that the next element 
of the list, in crder of ascending internal key 
values, will be used to determine which 
(sub) record will be transmitted# (If the internal 
BEAD cursor was reset, the element having the 
lowest internal key value will be used# If the 
internal PEAE cursor was on the last element, the 
cursor will be reset, a key error condition will 
be raised, and no (sob) record will be 
transmitted.) 

If the LIST clause is followed by a KEY clause, 
the value of the rel-key expression will be 
converted to a fixed binary integer of maximum 
precision. 

If rel-key has a value of xero, the internal BEAD 
cursor of the list will be reset. No (sub) record 
will be transmitted and no error condition will be 
raised • 

If rel-key has a negative value, such as -1, the 
internal PIAD cursor of the list will be 
decremented to indicate that the previous element 
of the list, in order of internal key values, will 
be used to determine which (sub) record will be 
transmitted. (If the internal BEAD cursor was 
reset, the element having the highest internal key 
value will be used. If the internal BEAD cursor 
was on the first element the cursor will be reset. 
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a key error condition will fee raised, and no 
<sub) record will te transinitted*) 

If rel->ey has a positive value the internal HEAD 
cursor of the list will be set to indicate that 
the element in the rel-key position of the list 
will be used to determine which (sab) record will 
be transmitted, (If rel-key is greater than the 
number of keys in the list, the cursor will be 
reset, a key error condition will be raised, and 
no (sub) record will be transmitted.) 

e. If the PEH EOBFIIE file-positioning option is 
specified, the parent record of a current 
subrecord will be transmitted. The value of the 
ctlfield expression will be converted to a 
character string the first eight characters of 
which identify the subfile control field* A 
current sufcrecord of the subfile must have been 
established by a HEAD SUBFILE statement when the 
READ PER SCEFIIE statement is executed* The 
internal parent key field value on the suhrecord 
will be used to determine which record will be 
transmitted. 

f. Ho KEYTO option is provided. A GET FIEID 
statement, following a BEAD statement, may be 
used for this purpose* 

4. Any READ statement referring to an UPDATE file 
will cause the record to be locked for exclusive 
use unless the NOLOCK option is specified* A 
locked record cannot be READ by any other task 
until it is unlocked* Any attempt to READ a 
record locked by another task results in a wait* 
Subseouent unlocking is accomplished by the 
locking task through the execution of an UNLOCK, 
READ, LOCATE, CLOSE or implicit close operation on 
the file* 
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•The HEAD INDEX Statenent* 

The HEAD INDEX statement causes an index record to be 
transmitted from the data base and established as the 
current record cf the index. 

General Format: 

HEAD FILE ffile-name) INDEX (indfield) <index-positioninq>: 
where index-positioning may be: 

BACKHANDS t KEY (expression) 

Syntax Pule; 

The READ INDEX statement must be a subargument in a DB 

preprocessor function reference* 

General Pules: 

1. The FILE clause specifies the data base file from 
which an index record is to be transmitted. It 
may net be an OOTPOT file. 

2. If the file is net open, it will be opened 
automatically unless BACKHANDS is specified. 

3. The INDEX clause specifies the index file from 
which the index record is to be transmitted. The 
indfield expression value is converted to a 
character string, if necessary, the first eight 
characters of which identify the indexed field. 
If the user who executes the HEAD INDEX statement 
is not the owner of the file, the indfield may not 
specify a field that the owner has not authorized 
the user to GET* 

4a. If nc index-rcsitioning option is specified, the 
file must be an IHPDT file. The next sequential 
index record, following the one previously read, 
will be transmitted. If the index file has not 
been previously read, the record having the lowest 
indexed field value will be transmitted. 

b. If the BACKNAFDS index-positioning option is 
specified, the file must be an INPUT file. The 
previcus sequential index record preceding the 
one previouslv read will be transmitted. If the 
index file has not been previously read, a file 
positioning error condition will be raised. 
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c. If the KE7 index-positioning option is specified, 
the file may fce an INPUT or OPDATE file* The 
value of the expression will be converted to a 
varying length character string, if necessary, 
validated and/or converted to an internal index 
hey form and used to determine which index record 
will te transmitted. If the key cannot be found, 
a key error will be raised, but the index record 
having the next lover internal index key value 
will be transmitted* 

d* No KFYTO option is provided* A GET INDEX KEY 
statement, following a PEAt INDEX statement, may 
be used for this purpose* 

5* A FEAE INDEX statement never locks an index record 
for exclusive use* 
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’The BEAD SOBPItE Statement* 

The READ SUBFILE statement causes a subrecora to be 
transmitted from the data base and established as the 
current subrecord of the subfile. 

General Format: 

BEAD FILE (file-name) SDBFILE (ctlfield) <subfile-positioning> 

<NOLOCK>; 

where subf ile-pcsiticning may be: 

BACK«AEDS } KEY (expression) 

Syntax Buie: 

The BEAD SUBFILE statement most be a subarqument in a 

DB preprocessor function reference. 

General Buies: 

1. The FILE clause specifies the data base file from 
which a subrecord will be transmitted. It may not 
be an output file. 

2. If the file is not open, it will be opened 
automatically unless EACKSBBDS is specified. 

3. The SOEFIIE clause specifies the subfile from 
which the subrecord is to be transmitted* The 
ctlfield expression value is converted to a 
character strinq, if necessary, the first eiqht 
characters of which identify the subfile control 
field. If the user who executes the READ SUBFILE 
statement is not the owner of the file, the 
ctlfield may not specify a subfile that the owner 
has net authorized the user to BEAD. 

q.a If no subfile-positioning option is specified, the 
file must be an INPUT file. The next sequential 
subrecord following the one previously read, will 
be transmitted. If the subfile has not been 

previously read, the subrecord having the lowest 
subrecord ID hey value will be transmitted. 

4. b If the BACKWARDS subfile-positioning option is 

specified, the file must be an INPUT file. The 
previous sequential subrecord, preceding the one 
previcuslv read will be transmitted. 

4.C If the KEY subfile-positioning option is 
specified, the file may be an INPUT or UPDATE 
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file. The "value of the expression will be 
converted to a varying length character string, 
if necessary, converted from numeric character to 
binary 7) internal subrecord key form and 

used to determine which subrecord will be 
transmitted. If the subrecord key cannot be 
found, a key error condition will be raised, but 
the subrecord having the next lower internal 
sufcrecord key value will be transmitted. 

4. a No LIST subfile-positioning option is provided for 
the READ SOBFIIE statement; the regular READ with 
IIST file-positioning may be used for this purpose 
because the list determines if and which subfile 
is to be accessed. 

4.e No subf ile-pcsitioninq option is provided for 
reading the region of subrecords dependent on the 
current root record; GET SDEFILE IIST SET followed 
by READ IIST statements (with forwards or 
backwards positicning) are very flexible for this 
purpose. 

4. f No KEYTO option is provided, A GET FIELD 

statement, following a BEAD statement, may be 
used fcr this purpose. 

5. A READ SOBFIIE statement referring to an UPDATE 
file will cause the subrecord to be locked for 
exclusive use unless the NOLOCK option Is 
specified, A locked subrecord cannot be READ by 
any other task until it is unlocked. Any attempt 
to READ a subrecord locked by another task results 
in a wait. Subsequent unlocking is accomplished 
by the locking task through the execution of an 
UNLOCK SOBFIIE, READ SUBFILE, or LOCATE SUBFILE 
operation on the subfile or a CLOSE or implicit 
close operation on the file. 
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•The FEPUT Statement* 

The REPUT statement replaces a data element in the current 
record or sntrecord ot an UPDATE file for subsequent 
retransmission to the data base; it may cause the value to 
be validated and/or converted to an internal form and it may 
also cause a crcss-reference to be automatically deleted and 
another entered in an index file. The REPOT statement may 
be used to delete a vhole record or subrecord and all 
cross-references to it in index files. 

General Format: 

REPOT FILE (file-name) FIELD (field-name< , field-name> ...) 

FROM (expressicn<, expression> 

Syntax Rules: 

1, The REPOT statement must be a subargument in a DB 
preprccesscr function reference, 

2, Several data element values can be replaced by one 

REPOT statement. In this case, a corresponding 
expression must be specified for each 

field-name. 

General Rules: 

1, The FILE clause specifies the data base file to 
which the data element value is to be subsequently 
retransmitted. It must be an OPDATE file owned by 
the user who executes the REPOT statement. It may 
not be an associated file or an index file, 

2, A current exclusive record of the file must have 

been established when the REPOT statement is 
executed. Several REPOT statements may be 
executed on a current exclusive record of the 
file. / 

3, The field-name is an expression that specifies the 

name of the data tase field whose data element 
value is to be replaced. The value of the 
expression is converted to a character string the 
first eight characters of which identify/ the 
field. / 

a. If the field is the key field of an anchor r4cord, 
the expression in the PROM clause oust have a null 
value (zero length) and the whole root record and 
all of its dependent subrecords in all subfiles of 
the FILE will he deleted. 
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b* If the field is the key field of a subreccrd, both 
the subreccrd and its parent record oast be 

current. The expression in the EROE? danse mast 
have a null value (^ero length) and the whole 
subrecord will be deleted* 

c. Otherwise the field-name may not specify a 

read-cnly field. 

If the field is not subdivided into elements, its 
value will be replaced. If the field is a 
multiple-element field, the element taken by the 
last GET of the FIELD since the current 

(sub) record cf the file was BEAD will have its 
value replaced* If no element was fpimd fpr tie 
GET FIEID or if no GET of the FIELD of the 

current (sub) record of the file was executed, an 
errcc condition Is raised. 

4* The expression in the FROE clause specifies the 

new data value to be given to the field element. 

The value cf the expression is converted to a 
varying length character string, validated and/or 
converted to an internal form and moved into the 
current (sub) record of the file. (If the data 
base field element is variable-length and the new 
valuers length is different from the old, other 
field elements ate automatically shifted as 
necessary*) 

5a. If the data base field is the key field of the 
anchor record and the expression in the FROM 
clause has a null value, all crcss-references to 
the )?ev of the parent record and its dependent 
subrecords will be automatically deleted from all 
index files fcr the file specified in the FILE 
clause* 

b. If the data base field is the ID key field of a 
subrecord and the expression in the FROM clause 
has a null value, all crcss-references to the ID 
key of the subrecord will be automatically deleted 
from all index files for the subfile* 

c* If the data base field has an index file, the 
cross reference of the old internal data element 
value will be automatically deleted, and a 

cross-reference of the new internal data element 
value to the key of the record will be 

automatically entered in the index file. 

6* The (sab) record with the new data element value 
will be retransmitted to the data base when an 
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UNLOCK Statement for the (sub) file is execotea or 
immediately before the next LOCATE or EEAC on the 
(sub) file or immediately before the next CLOSE or 
autcmatic close operation on the file. 
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•The SET tIST ITKE LIST Statesent* 

The SET LIST LIKE LIST statement dynamically allocates main 
storage for a new list to later contain an estimated number 
of keys, copies the key field name and conversion routine 
name etc*, froir an existing list, and sets a pointer 
identifying the new list* 

General Format: 

SET LIST <new-list-pointer) SIZE (dimension) LIKE LIST 

(list-pointer) ; 

Syntax Rule: 

The SET LIST LIKE LIST statement must be a subargoment 

in a DB preprocessor function reference* 

General Rules: 

1* The list-pointer in the LIKE LIST clause must be a 
pointer expression that identifies a list of keys 
in main storage to be referenced for prefix 
inforiration such as key element length etc. In 
the exceptional case of a list pointer having a 
NOIL pointer value, a NULL pointer value will be 
returned* 

2. The SIZE clause specifies an estimate of the 
number of keys that will subseguently be put into 
the new list* For example, it could be the #LIST 
count of the existing list or a multiple of it* 
The dimension expression value will be converted, 
if necessary, to a fixed binary integer of maximum 
precision and used to govern the allocation of the 
first segment of the new list, 

3, The new-llst-pointer in the SET LIST clause 
specifies the user's pointer identifying the new 
list of keys in main storage. It must he the 
identifier of a pointer variable declared by the 
user* Regardless of its former value, it will be 
set to identify the new list of keys in main 
storage* The new list remains allocated in main 
storage until the user executes a FREE LIST 
statement* 



PAGE 05 


•The OLIST Function* 

IJLIST buiias a copy c£ a list of Iceys omitting duplicated 
tey values and returns a pointer value identifying the new 
list to the point of invocation# If The given list has only 
unique 3tey values, OUST returns the given list pointer 
without copying the list* 

Befernece: 

OLIST (list-pointer) 

A DUST functicn reference is used as or in an expression; 
it is not to be a sutargument in a DB preprocessor function 
reference* The user may not declare any attributes for the 
OLIST function; the fcllowinq statement will be generated 
automatically; 

DECLARE OLIST EKTIiy (POINTER) EETORNS (POINTER) ; 

Argument: 

The list-pointer argument must be a pointer expression that 
identifies a list of keys in main storage. It must have 
been set when the OLIST function is invoked. 

Result; 

The value returned by the OUST function is a pointer 
identifying the new list having only unique key values* 
However, if the argument list is found to not have any 
duplicated key values, its list pointer is simply returned 
(this always happens when the argument list is null or has 
only one key) * 
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•The UNLOCK Statefflent* 

The UNLOCK statement makes a locked current record or 
subrecord available to other tasks for BEAD operations; it 
may cause transmission of the current record or subtecord to 
the data base* 

General Formats 

UNLOCK FILE (file-name) <SDEFIIE (ctlfield) >; 

Syntax Rule: 

The UNLOCK statement must be a subargument in a DB 

preprocessor function reference* 

General Rules: 

1. The FILE clause specifies the data base file whose 
current record is to be unlocked. The file must 
have the UPDATE attribute. 

2* A record can be unlocked only by the task which 
locked it. 

3a* If no SUBFILE clause is present, the current root 
record will be unlocked. 

3b. A SUBFILE clause, if present, specifies that the 
current subrecord of a subfile is to be unlocked. 
The ctlfield expression value is converted to a 
character string the first eight characters of 
which identify the control field. 

4, If the locked current (sub) record has been updated 
by a PUT or REPUT FIELD statement, the UNLOCK 
statement will cause it to be retransmitted to the 
data base. It continues to be the current 
(sub) record of the file, but POT and REPOT 
statements are invalid until another current 
(sub) record is established* 

5. Unlocking a (sub) record that was READ with the 
NOLOCK option or that has already been ONLOCKed 
has nc effect. 
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•The UPLIST Function* 

Unique Parent LIST builds a list of the unique parent (root) 
record kevs froa a alven sob-record (children) key list and 
returns a pointer value identifyinq the new list to the 
point of invocation* The new list has the sacae number of 
parent keys as the number of subrecord keys in the qiven 
list* Parent keys will net be repeated, even if more than 
one of the given subrecord keys are dependent on a 
particular parent record* 1 previously current and updated 
subrecord of the subfile referenced by the given list will 
be transmitted to the data base. The subrecord identified 
by the last key in the qiven list will remain as the current 
subrecord of that sub-file; any current root or index 
records or subrecords of other subfiles will remain current. 
The PEAD cursor of the qiven list will be reset. 

fief erence: 

DPLIST (file-name, cbild-list-pointer) ; 

An UPLIST function reference is used as cr in an expression; 
it is not to he a subarqument in a DB preprocessor function 
reference. The user may not declare any attributes for the 
UPLIST function; the followinq statement will be generated 
automatically; 

DECLARE UPLIST ENTRY (, PTH) RETURNS (PTH) ; 

Arguments: 

The file-name argument specifies the data base file from 
which subrecords are to be transmitted. It may not be an 
OUTPUT file. If the file is not open, it will be opened 

automatically. The file-name must be used in at least one 
DBPL/I statement elsewhere in the program. 

The child-list-pointer argument oust be a pointer expression 
that identifies a list in main storage of subrecerd keys 
from the data base accessed by file-name. It must have been 
set when the UPLIST function is invoked. 

Result; 

The value returned by the UPlIST function is a pointer 
identifying the new unique parent list. The new list will 
be in order of ascending internal parent key values without 
duplicated values. If the given subrecord list is null, a 
NUII pointer value will be returned. 
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•Tbe SPITE Stat€aent* 

The SSITE statenient causes a physical record (presuaably , 
from a backup file) to he transmitted to a SEOtJESTIAL OUTPUT 
file. 

General Forisat: 

SHITE FILE (file-name) FHOH (variable) ; 

Syntax Buie: 

The SHITE statement most be a subarguiaent in a DB 

preprocessor function reference* 

General Hules: 

1, The FILE clause specifies the file to which the 

record is tc be transmitted* It must be a 
SEOTIERTIAt OUTPUT file owned by the user who 
executes the SHITE statement* 

2* If the file is not open, it is opened 

automatically with the SEQOENTIAI OUTPUT 
attritotes. 

3* The variable in tbe FBOU clause, declared and 

filled by the user, contains the record to be 

written* It must have the self-def ininq format of 
an internal variable-length record* Its key field 
value (without validation or conversion) must be 
higher, in order of ascending internal values, 
than that cf the record transmitted by the 
previous WHITE statement for the file. (The 

record does not become the current record of the 
file for purposes of POT statements*) 
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•Th€ #XPEF Function* 

#XREF calculates the noraber of cross reference keys in the 
current record of an index and returns it to the point of 
invocation. 

Beference: 

#XBEF (file-narae, indfield) 

A #XBEP function reference is used as or in an expression; 
it is not to be a subarqoEent in a DB preprocessor function 
reference. The user may not declare any attributes for the 
#XBEF function; the fcllowing statement will be generated 
automatically: 

DECLARE #XBEF ENTE? CHAR (8) ) RETORNS (FIXED BIN(31)); 
Arguments: 

The file-name identifies a data base file. It may not be an 
OOTPOT file. 

The indfield specifies the index file, A current index 
record must have been established by a READ INDEX statement 
when the #XREF function is invoked. The indfield expression 
value is converted to a character string, if necessary, the 
first eight characters of which identify the indexed 
field. 

Result; 

The value returned by the fXREF function is a binary integer 
of maximum precision giving the number of cross-references 
in a current index record. If an index record is not 
current, a zero value .will be returned. 
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FIGURE 1. FORMATION OF LISTS 
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APPENDIX A. 


FItE LEVEL STATEMENTS 


ON EPRONFILE (mfcb) | SYSTEM I 

|_GC TO label_1 ; 


OPEN PILE fnfcb) <TIT1E (•mfcb*)> 1 CIRECT I I INPUT | 

|_SEQOENTIAL_| { OUTPUT |; 

I UPDATE ! 


CLOSE PILE (mfct) <ERASE>; 


EICOBt LEVEL STATEMENTS 


LOCATE FILE (mfcb) 1 KEYFEOM (expr) | 

l^SUEPILE (scfn)_| ; 


READ FILE (aifcb) | forwards I <NOLOCK>; 

1 BACNKABDS ! 

I KEY (expr) I 

I LIST (ptr) <KFY(n)> | 

f_PEF SUEEILE (scfn) 


BEAD FILE (tpfcb) SOEFIIE (scfn) | forwards t <N010CF>; 

j EACKNARDS | 

I^KEY (expr) I 


READ FILE (wfcb) INDEX (ifn) ( forwards ) 

I BACKWARDS | ; 
|_KEY (expr) f 


UNLOCK PILE (rafcb) <SUEFILE (scfn)>; 
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PHYSTCAl FECCfiD STATEMENTS 

GST FILE (fflfcb) RECCED INTO (var) ; 

URITE FILE <ofcb) FROM (var); 

FIELD LEVEL STATEHENTS 

POT FILE(nifcb) FIELD (fn<, fu2>) FROM (expr<,expr2>) ; 

GET FILE<ntfcb) ETELD(fn<,f n2>) INTO (var<,var2>) ; 

GET FILE(tafcb) IKDEX(ifn) KEY INTO (var); 

REPOT FILE(mfcb) FIELD (fn<,fn2>) FROM (expr<, expt2>) ; 
fuUword = #FIE1D (rofcfc, fn) ; 
fullword = #XEFF (mfct,ifn); 

DATABASE LIST STATEMENTS 


GET FILE (mfch) | SOEFILE (scfn) \ LIST SET (ptr) ; 

I INDEX (ifn) I 

] anchor is index 


GET FILE fmfcbl <SOBFIIS Iscfn) > KEY SET (ptr); 


Ptr = CCLIST (ipfcb, scfn, ptrl) ; 


Ptr = CPLISI (mfcb, ptrl); 


Ptr = OPLIST (mfcb, ptrl); 


NON-DATAEASE LIST STATEMENTS 
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CN IISTEBBOB \ S?STE» | 

t_GO TO label_| ; 

GET LIST (Dtr) KEV (0); 

GET LIST (ptr) KEY <<n)> INTO (var) : 

GET LIST (ptrl) FEY SET (ptr2> ; 

Ptr ^ ULIST fptrl) ; 

Ptr = DGPLIST (ptr1> ; 

Ptr = LIST (ptr1,op,ptr2) ; 

SET LIST (Ptr2) SIZE (aim) LIKE LIST (ptrl); 
GET LIST (Ptrl) INTERNAL KEY INTO (var); 

POT LIST (ptr2) INTERNAL KEY FROM (expr) ; 
Fullword = #LIST (ptr); 

FREE LIST (ptr <,ptr2>); 


FREE LIST 
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diffi 

expr 

fn 

ifn 

afcfc 

n 

op 

ptr 

scfn 


GICSSABY 

au expression resulting in a numerical 

dimensicn value 

an expression resulting in a value 

an expression resulting in a field name 

an expression resulting in an indexed field 
name 

trainline FILE control block name 

an expression resulting in a numerical 

subscript value 

list operator: '1* or or 

pcintec to a list of keys in main stroage 

an expression resulting in a subfile control 
field name 


var 


variable data area name 
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TOPIC C,2 - CON^EPSICK, V&IIDATICW, AND FOPfiATTING 
PCnTINE TEST DPI7EP PEFEBENCE MANUAL 


I. INTRODUCTION 

The RDEDRIVE prcgram is a facility to allow the 
prograiDffier to test ccnversion, validation and 
formatting routines ccnversationally. The user can 

specify the tcotine names and the input data values* 
This eliminates the need for a test data base, and 
provides an efficient method for testing exit 

routines* 

II. LINKING EDPDPIVE 

RDBDRIVE is a standard part of NASIS. Because its use 
is limited to the programmer, it is not a part of the 
standard user profile. 

To use EDBDRIVE it must be entered into your user 
profile. To do so, the following commands must he 
executed : 

SyNCMIM DPI7PR=*CCHHAND 

DBF A Oil KTTVEPBS**'DRIVEP*DBE8IVE" 

PROFILE 

APOFF 

DRIVER now becomes a valid NASIS command, and will 
Invoke the test driver. 

III. OPERATIONS 

A. Input Bode 

Upon initiating SEBDRTVE the user is prcmpted to 
select an infut mode. This is the format to 
which his tetifinal input (which, by the nature of 
the terminal must be alphanumeric) is translated 
before it is sent to the first routine in the 
string of routine names. 

The available options are; 

a - alphanumeric, 
f = full word, 
h = half word, 

1 = long floating point, 
p = packed decimal, 
s = short floating point, 

X = hexadecimal. 
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A null response or an *'EKD" response to the prompt 
for input mode will result in program termination. 
Any other response is invalid^ a diagnostic is 
issued and the user is reprompted for the input 
mode. 

Routine Names 

The user is next prompted to enter the routine 
names he wishes to test. The routine names must 
be ented in the order; conversion, validation, 
formatting. Any routine may be defaulted to 
null, positionally; i,e*, only the following 
combinations are valid: 

a 

a,b 
a ,b,c 
a, ,c 

,b,c 
, ,c 

Where: 

a a conversion routine name, 
b a validation routine name, 
c a reformatting routine name, 

A null response returns the user to the prompt for 
input mode. 

The only validation chect made on the routine 
names is to insure that none of the names exceed 
eight characters. If any do exceed eight 
characters, the entire string is rejected and the 
user is reprcmpted for the names. 

If the user has specified a validation routine, he 
is DOW prompted of any validation arguments. This 
may be any character string, up to a maximum of 
fifty bytes. 

Input data 

After the input mode has been selected and the 
routine names specified, the user is prompted to 
enter his routine input data. The input data is 
subject to the restrictions of the specified input 
mode, as follows: 


1 


Alphanumeric 
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2 . 


3. 


4. 


a. 256 character maxiniuii! string. 
Eull 

a. nucerics and sign only, 
fc. fractions truncated, 
c* 2,147,483,647 maximum, 
d. -2,147,483,648 minimum. 

Half word 

a. numerics and sign only, 

1. fractions truncated, 

c. 32,767 maximum, 

d. -32,768 minimum. 

lonq flcatinq point 

a. numerics and sign only, 
t. fractions truncated. 


5. Packed decimal 

a. numerics and sign only, 
h. decimal point ignored, 
c. 15 diqits maximum, 

6. Short floating point 

a. numerics and sign only, 
t. fractions only. 

7. Hexadecimal 

a. numerics and A-T only, 

b. even number of characters only, 

c. 256 character maximum string. 

Any input errors vill result in an appropriate 
diagnostic. The bad string will be reiected and 
the user will be reprompted for input data. 


A null response will return the user to the prompt 
for routine names. 


One special response exists. That is NOIL. This 
response will result in a null value being 
converted to the specified input mode. This step 
is necessary, since any null response to the 
prompt for input data will cause the user to be 
reprompted for routine names. 

The incut data is displayed to the user, first as 
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he entered it, fcr verification. And next, in its 
new form, as it will go to the first routine 
specified. 

The input data is passed to the first routine name 
specified, for processing. The output from this 
routine then becomes input for the next routine in 
line. 

D, Output 

The cutput from each routine is labeled and 
displayed to the user in hexadecimal. The output 
from a formatting routine is also displayed in the 
character foruat. 

Any errors during processing will result in a 
dianostic message. The user will then be 
reprompted for input data, 

E, Termiraticn 

As previously noted, null responses to the program 
prompts will filter the user back to the prompt 
for input mode, and a null response or "END" will 
cause program termination. No more than three 
null responses sill ever be needed to terminate 
the program. 

Another method of termination is merely a VEND* 
response to any Prompt. 
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APPENDIX A. 

SAMPIE Test Driver Session 


begin nasis 

BKTEB NASIS COMMAND: driver 

SELECT INPDT MODE: t 

ENTER POOTINE NAMES: dbcvtsn, ,dbfratsn 

ENTES DATA VAIOE: +12345 

DATA VALUE = +12345 

ROOTINE INPDT VAIOB = 12345 

AFTER CCN7EPSI0N, HEX = 3039 

AFTER REFORMATTING, HEX = F1F2F3F4F5 
AFTER REFORMATTING, CHAR = 12345 
ENTER DATA VALUE: {null response) 

ENTER ROUTINE NAMES: (null respose) 

SELECT INPUT MODE: X 

ENTER ROUTINE NAMES: ,,dtfntsn 

ENTER DATA VAIDE: 3039 

DATA VALUE = 3039 

ROUTINE INPUT VALUE = (unprintable) 

AFTER REFORMATTING, HEX == F1F2F3F4F5 

AFTER REFORMATTING, CHAP = 12345 

ENTER DATA VALUE: /END 

ENTER NASIS CCMMAND: 
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TOPIC C,3 - HESSAGE BILE ECITOR USER'S GDIDE 


!• INTBODtlCTICN 

The EDIT ccfflisandi provides a user with the capability of 
creatinq, updatinq, and reaioving entries within a copy 
of IISBKIB. 

BDBHLF is a standard part of NfiSIS, however, becaase 
its use is limited to the application programmer, it is 
not a part of the standard user profile. 

To use FDBHLP it must be entered into your user 
profile* To dc so the following commands must be 
executed : 

SYNONYM EDIT=*COnMAND 
DEFAOIT MTTVEBES='EtIT=I)BKlB* 

PPOBItE 

APOFF 

In order to familiarixe a user with the mcdule, a 
description of the file characteristics is necessary* 

IT. REGION CODE 

The file is broken down into two areas: one containing 
terms for EXPLAINation and the other for module 
messages* 

A* TEEMS 

There are two types of terms each comprising their 
own regional code characteristics* 

1. GICBAI terms 

A global term is one which has a constant 
definiticD, throughout the NASIS system. The 
region cede is derived from a period and the 
first seven or less characters of the term 
being defined. The term is left justified 
and blanks filled* 

EXAMPLE; term region 

FOPflAT .FORMAT 

STRATEGY .STBATEG 

2* File term 
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A file term is one which has a set definitioc 
for a particular file within the BASIS* The 
region code is derived fro® the file na®e (6 
characters Barimum) ^ a period (.), and^ the 
first character of the term being defined* 
The file name is left iastified and fclanic 
filled. 

EXABPIE: file-name term region 

RSBDI ADTHOB ASBDI .A 


B« nodule messages 

Each module message contains a unique region code, 
within that region there are three areas used for 
defining the message. They are the message, 
explanation of the messsage, and the responses to 
the message. The region code is derived from the 
message code itself. It is left justified and 
blank filled to 8 characters* 

EXAMPIE; message-id region 

DBEtPOl OBH1F01 


III* PILE OBDEBING BY KOHEPTC KEY 


The numeric key provides file sequencing of each entry 
within a given region* The region code provides for a 
partially alphatetically ordered file. The numeric 
key maintains sequencing of all entries which develop a 
duplicate region code (terms only). 


A. TEPMS 

Terms are in numeric sequential order within a 
region using a seven digit key and a constant 
increment of 10. 

B. Module messages 

Messages alsc maintain a seven digit key and a 
constant increment of 10. However, a breakdown 
of the numeric key provides partitioning of the 
region code into the message content, explanation 
and response. Numerically the key is governed as 
follows: 

a. message key range 00-90 

explanation key range 10C-390 

response key range 400-9999990 
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I?. OUIQUE CHAFJCTBBTSTICS OF AN ENTRY 
A* Tera indicaticn 

Because of duplication of regional codes every 
term is suffixed ty a colon 

EXAMPLE: Term Region Code Key Record Content 

FCEEAT .FOBWfiT XXXXXXO FORHAT:"text" 
Coctinuaticn Convention 

The continuation convention for EXPLAIN is of tvo 
types: physical and logical. They are represented 
by a ipinus (-) and a plus (♦), respectively. 
These are ccntrol characters only, and are not 
displayed to the NASIS user. 

1. PHYSICAI 

A physical continuaticn implies a continued 
line «ill be displayed concatenated vith the 
previous line. The contextual method of 

ccntrclinq physical continuation is under 
program control. A minus (-) at the end of a 
text line indicates physical continuation. 

2. lOGICAl 

R logical continuaticn implies that a nev 
line will be displayed on the output device. 
A plus {*) at the end of a text line 
indicates logical continuation. The 

contextual method of indicating logical 
continuation is by a double slash (//) at the 
end of each louical line. 

V. COWHAND DEFINITION 

There are six user commands available for manipulation 
of the LISBMLF file. 

A. ADD: 

The ADD command will create a new entry in the 
message file cr concatenate new text lines to an 
existing entry in the message file. 

E. DELETE: 

The EELETE ccmmand allows the removal of one or 
more text lines or an entire entry in the message 
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file. An atsolute match is made on the entr^ 
before deleticn is allowed. 

C. FEPIACEt 

The BIPIACE conmand allows the replacement of a 
single entry in the message file with one or more 
new text lines. An absolute match is made on the 
entry before replacement is allowed. 

D. DISPlAl: 

The DISPLAY command allows one or more text lines 
or an entire entry to be displayed on the output 
device. 

E. PREFIY; 

The PBEFIY ccmmand allows the modification of the 
filter code of each message or all succeeding 
messages* 

F. END: 

The END command causes termination of the EDIT 
command processor* In addition the use of /END 
on ATTN: will cause termination of the current 

parameter prompt and a command prompt will be 
returned to the terminal* 

CONMANC SYNTAX 

ADD (id) , TYPE, TEXT 
DELETE id, TYPE (,n1(,n2)) 

DISPLAY (id), TYPE (,n1(,n2)) 

PEPLACI id, TYPE, N1, TEXT 
PREFIX filter code 
END none 

Where? 

id 

is 1 to 8 characters in length depending on 
the follcwing constraints: 

a. If the “type” parameter contains one of 
the keywords (MSG, EXP, ESP) then id may 
be up to 8 characters in length* 

t. If the type parameter is defaulted to a 
term i*e., keyword not specified, then 
the id may be up to 6 characters in 
length. 
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c. The id contains the hevword GLOBAL, (The 
reqion is developed from the first seven 
(or less) characters of the term 

supplied in the type parameter. 

NOTE; The user is allowed to default the id 
parameter when usinp the ADD or DISPLAY 
commands* The default value is the id 

specified by a previous command. 

type 

is either MSG, EXP, BSP, or a term, such 
that; 

MSG implies message text, 

EXP implies explanation text, 

PESP implies response text, or 
term is the string to be EXPIAINed. 

text 

is a string of characters that is to comprise 
the text line(s). Separate but related 
physical text entities may be separated by a 
double slash (//): this accomplishes logical 
continuation* 

n 1 

is a starting line number at which the text 
is to be DEIETEd, PEPLACEd, or DISPLAYed, 
The default values apply only to the DELETE 
and DISIIAY commands* The assumed values are 
as follows; 

COOOCOO for Type of MSG, 

0000100 for type of EXP, 

C000400 for type of EESP, 

The default value for terms is determined by 
finding the specified term within a region* 

n2 

is an ending (inclusive) line number to be 
deleted or displayed. If omitted, only n1 
will be involved* 

filter code 

is a two character filtering prefix, set at 
any time by the PBEFIX command; this prefix 
will preceed each line (as per EXPLAIN 
reguirements. ) 
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TOPIC C,4 - - JCINING NEW nSEBS 


I. I8TB0DUCT1CN 

The JOIN coffiiuand gives the NASIS Data Base 
Administrator the ability to control the access of 
retrieval users to the various files of the system. In 
addition, it also allots the DBfi to specify passwords, 
time slice values and authority codes which influence 
use of the system. The information is maintained in 
data set NASIS. USERIDS. 

II. COMMANDS: 

JOIN 

The JOIN command establishes a new NASIS-ID which can 
be used to access the system. This is accomplished by 
creating a new record in the data set and inserting the 
values for the various data fields. 

Cooraand: JOIN 

Operands: NA SI SID=id, PASS wCED-code,TS= value, 
AOTH=authority,FILES=file list 


Where: 


id 

identifies the new NASIS-ID to be created. 


Specified as: a 1-8 character alphanumeric value 

beginning with a letter. 

, code 

identifies the password or indentif ication code to 
be used for this NASIS-ID. 

Specified as: a 1-8 character alphanumeric 

value • 

Default: No password will be assigned. 


value 

indicates the magnitude of the time slice in Milli 
Seconds to be assigned to this NASIS-ID under MTT 
mode cf operation. 

Specified as: a 1-5 digit numeric value, 

authority 

indicates the authority level to be assigned to 
this NASIS-IC under MTT mode of operation. 
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Specified as: a one character code, *0* for user 

or for DEA. 

Default: *0* »lll be assiqned* 

file list 

identifies the files to be made available to this 
NASIS-IC. 

Specified as: a list of fully qualified file 

names, i*e* lEA-IC* FILE-ID* 


OUIT: 

The CUIT ccffiffiand removes a NASIS-ID from the list of 
valid ids* 


Command: QDIT 

Operand: KASlsiD=ld 


CHANGE: 

The CHANGE command is used to alter the values of one 
or more of the data fields (other than the file list) 
associated eith a particular NASIS-ID* 

Command: CHANGE 

Operands: NASISID=id,PASSWORD=code*TS-value, 

AUTH=authority 


ADD: 

The ADD ccmntand is used to specify new files which are 
to be added tc the list of files to which a qiven 
NASIS-ID is permitted access* 

Command: ADD 

Operands: NASlSIC=id,FIlES=file list 


DELETE: 

The DELETE command is used to remove files from the 
list of files to which a particular NASIS-ID is 
permitted access* 
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ComiaaTid; EilETE 

Operands: HASISID=id,FIlES=file list 


DISPLAY: 

The DISPLAY coHiniand is nsed to list the files available 
to a particular NASIS-ID, along with the other data 
values present in his identification record* 


Cofflinand: DISPLAY 

Operand: BASISIE=id 

III. EXAMPLE 


USER; 

SYSTEM: 

DSEfi: 

SYSTEM: 

USER: 

SYSTEM: 

USER: 

SYSTEM: 


icin iohn , ace, 99999* , 

JOBS JOINED TO NASIS 8ITH PASSWOFD=ACE, 
TIBESLICE=99999 MILLESECONDS , AND ADTROBITY=. 
add iobn, (safety. asrdi,safety*erts) 

Adds the two files to the list of files 
availafcle to JOHN* 
display ichn 

Cisolay the current information maintanined 
fcE JOHN. 

change john.auth^d 

Applies the appropriate change* 
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TOPIC D* 1 - BAINTEUANCE SUBSySTEH 


I. IBTBODDCTIC?! 

The maintenance ccumands provide for file definition, 
creation, maintenance, and statistical reporting* The 
Descriptor Editcr provides the data base administrator 
with an interactive means of defining the data fields 
comprising a data base. File creation function is 
accomplished by EELOAC, a generalized loading program, 
which supports several input data formats* File 
maintenance can he performed either on-line, by an 
interactive data editting capability, or off-line by 
the generation of maintenance transactions which can be 
grouped, validated and applied under the direction of 
the data base administrator. Concurrently the system 
maintains statistical information on the maintenance 
activity of each file* 

II. THE HAINTAIK COBBAAD 

To initiate the Maintenance Subsystem, the user must 
enter the MAIMTAIM command, e*g*: 

-ENTEB BASIS CCPHANDr maintain 

The user may now enter any of the Maintenance Commands, 
such as; COMBINE, COBPECT, EDIT, INVERT, LOAD, PRINT, 
or OPDATE. 
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TOPIC D,2 - DESCPIPTOP ECITOB 


I, INTPODUCTICH 

the Descriptor Editor is an editing program used for 
creating and updating the field descriptors of a BASIS 
Data Base. 

II. INVOKING TEE EDITOF 

The Descriptor Editor is invoXed by entering the EDIT 
command and specifying the appropriate mode of 
operation. 

EDIT KCDE=<CEEATE|DPEA1E|REST0RE> 


Ehere: 

KODE 

Is Specified as: 

CEEATE; assumes that no data files exist and that 
the user is either creating or continuing to 
create field descriptors. 

UPDATE: assumes that data files do exist and that 
the user uisbes to modify the description of 
cne or more of the fields. The UPDATE mode 
allows tie user to make changes that do not 
affect tie physical format of the record* 

RESTOFEt reads in previously, check-pointed 
descriptors and continues processing in the 
CREATE mode. 

For all inodes tie first letter of the mode type is a 
sufficient abbreviation. If the entered mode value is 
invalid, the editor will re-prompt the user for a 
correct value. If the user defaults the prompt for the 
mode, the Editor vill terminate and control will be 
returned to the tfaintenance director. 

EXAMPXES: 

1. The user wants to create a new data base 
whose name is PEOPIE. 


SISTENl ENTER NASIS COHHAND: 
USES: MAISTAIF 

SYSTEM: ENTER PILE NAME: 

USER: EECPIE 

SYSTEM: ENTER: 
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DSE1»: EBIT 

SYSTEM; ENTEB ROBE; 

DSER; CREATE 

2. The user wants to taodify the descriptors for 
an eristinq data base whose name is PGRS, 

SYSTET; ENTER BASIS COMMAND: 

DSEH; MAINTAIN PGMS 
SYSTEM; SNTEB; 

OSER; EDIT OPDATE 

3* The user has a checicpointed set of 

descriptors for the data base GAMES which he 
wishes tc continue defininq* 

SYSTEM; ENTEH BASIS COMMAND; 

USER: MAINTAIN GAMES 

SYSTEM; ENTEB: 

OSER; EDIT RESTORE 

III. DEFINITIONS 

The followinq definitions are used throuqhout this 
section; 

1. Boolean Values - Used where ever a yes or no type 

of response is required. The followinq are 

acceptable values for a *Yes* type of response: 

YES, Y, TRUE, T, CN, 1. 

The followinq are acceptable values for a *no* 
type of response; 

NO, N, FAISE, F, CFF, 0. 

2. Fieldname - Is a character string of 1-8 

characters long of the followinq form; the first 
character must be alphabetic, and the other 
characters, if any, must be alphanumeric. 

3. Routine Name - Is a character string of 1-8 
characters long with the followinq form; the 
first character must be alphabetic, and the rest 
of the characters, if any, must be alphanumeric. 

IV. THE CREATE MODE CCEHANDS 

A. The ADD and CHANGE COMMANDS allow the user to 
create a new field descriptor or modify existing 
field descriptors. 
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ADD < ICHANGE) ILDNAHE^f ield-name, 

*IYPE= (FIDTYFE=f ield-type 

<,AIIGN=<RIGHT|LEFT») , 
FCEM=(riDFOHf!=field-format, 
rLDLEN=field-lenqth, 
ErsnLEN=eleraent-length, 
EIEHLIK=eleraent-noffiber 
<,OKIQDE=<Y|N») , 

FODTTNES^ (CONV=conversion -routine, 

FOR HAT= for mat ting- routine, 

VA1ID= validation -routine, 
VALTDASG=validation-argument) , 
IMDEXED= (INDEX=<YtN>, 

IFLDNAME=field-name 
<,EXTINT=<INTERNAL|EXTEHNAI>, 
EXTLEN=external -length, 
SPANNED=<Y|N») , 

ASSCCED= <ASSOC=<Y| N>, 

AFLDNAME-field-naroe) , 

SUBFILED^ (SaBFTlE=<YtN>, 

SFtDNAHB=f ield-name) , 

S0BFIE1D= (SUBFID=<Y1 N>,BA5EFLD=field-naiBe, 
OFFSET=offset 

<,<FIlE=<*filename| ANCHOR» 
or <FILE=<ASSOCIATED|SDBFIIE>, 
FIDNAME2*field-naifi€») 


Nbeie: 

FtDNAKE 

identifies the field tc be added. 

Specified as: a valid fieldname. 

FIDTYFE (FIEID TYPE) 

identifies the physical format of the 

field. 

Specified as: 

A - alphanumeric character string 

B - bit string 

PS - 8 bit unsigned binary number 

BP - packed bit string. These fields 
will be placed immediately after 
the key field as one contiguous bit 
string. 


BY - hexadecimal 
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IS - lartje numberic <32 tit signed 
binary number) • 

S - scientific <14 digit decimal number 
within the range of 10**-75 : 

1C**+75>. 

SD - scaled decimal (nine digit numbers 
within the range 10**-9 i 

10**+9)* 

ES - short numeric <16 bit signed binary 
number) • 

SS - short scientific (six digit 

decimal number within the absolute 
range of 10**-75 i 10**+75). 

AlIGN (ALIGNHEST) 

identifies right or left alignment of the 
field. 

Specified as: 'FIGHT* or *H* for right 

alignment and *IEFT* or *L* for left 
alignment* 

FLDPOEM - (FIEtD FOEMAT) 

identifies the logical format of the field. 

Specified as; F-FIXED, V-VAHIABXE, FE-FIXED 
ELEMENT, VE-VARIABLE ELEMENT. 

FtOLEK (FIELD LENGTH) 

indicates the length of fixed fields or the 
maximum length for other types of fields. 

Specified as; a positive number. 

(1) For the file key field, the maximum 

field length is 256. 

(2) For all other fields: 

<a) If FIDFOBM=F, then the maximum 
field length is 3996 minus the key 
field length; 

<b) For all other values of FIDFORM, 
the maximum length is 3994 minus 
the key field length. 

StEMLEN (EIFBENT lEKGTH) 

indicates the maximum length of fixed and 
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variallc elements. 

Specified as: a positive number with the 

ranqe of 1-256 if FLDFOEH is FS: the ranqe is 
1-255 if ILDFOEH is VE. 

EIEHLIM 

indicates the maximum number of elements 
allowed in the field. 


Specified ast a positive number. 


(1) 

If 

ELDFORM^FE, 

then the 

maximum 

number 

of 

elements 

is equal 

to the 

field 


length. 




<2) 

If 

FLDFOBM=VE, 

then the 

maximum 

number 

of 

elements is 

the field 

length 

divided 


by 

two. 





UNIQUE 

indicates whether or not all element values 
within a multi-element field are to be 
unique. 

Specified as; a boolean value. 

Eefault; N 

CONV (CONVEPSION POOTINE NAME) 

identifies the name of the routine used to 
convert the input data as it is placed into 
the data base. 

Specified as: a routine name. 

FCBMAT <POPMATTING ROUTINE NAHE) 

identifies the routine used to format the 

data for output from the data base. 

Specified as: a routine name. 

VAIID {VAIIDATION ECUTINE NAflE) 

identifies the name of the routine used to 
validate the input data. 

Specified as: a routine name. 

VALICARG (VA13DATICN ECUTINE ARGUHENT) 

indicates the argument required by the 
validation routine to validate the input 

values* 
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Specified ast a fiexadeciaial character string 
cf 1-100 characters. 


INDEX 

indicates whether the field is to be 

indexed* 

Specified as: a toolean value* 

lefault: N 

IFIENAME 

identifies another field previously defined 
with which this field is to be indexed* 

Specified as: a valid fieldname of a 

previously entered indexed field. 

tefault: the Editor assumes that this field 

is the first entered field of a new index 
file. 

EXTINT 

indicates whether the key of the index file 
is to be In internal or external form# If 
the key values are to be in external form, 
then the field values must be formatted 
before being placed on the index file. 

Specified as: INTEFNAt or I for internal 
form or EXTEENAl or I for external form. 

lefault: internal form, i.e., the value used 

cn the index file is the same as that stored 
in the anchor file. 


EXTLEN fEXTEBNAL lEWGTP) 

indicates the maximum length possible for an 
formatted value of the external field. 


Specified as: a positive numeric value in 

the range 1-256. 

NOTE: if the EXTINT entered value is 

external, then EXTLEN must he specified. 

SPANNED 

indicates that this index is to consist of 
spanned records. 


Specified as: a boolean value. 


Default: N 



PAGE 116 


NOTE: this iraplies that the utaximuiB length 

for index Veys can he no larger than 255 to 
allow for a one byte spanned counter. 

ASSOC (ASSOCIATED) 

indicates whether the field is to be 
associated* 

Specified as; a boolean value. 

Default; N 
AFIDNAME 

identifies another field previously defined 
with which this field is to be associated. 

Specified as; a valid previously entered 
field name. 

Default: the Editor assumes that this field 

is the first entered field of a new 
associated file. 

SUBFILE 

indicates whether the field is to appear on a 
subfile. 

Specified as: a boolean value. 

Default; N 
SFLDNABE 

identifies another field previously defined 
which identifies the subfile on which the 
field is to be placed. The field named may 
be the subfile control field. 

Specified as: a valid previously defined 

fieldname. 

SUBFLE 

Indicates whether this field is to be defined 
on either a part or the whole of another 
field. 

BASEFXD 

identifies the field on which this new field 
is to be defined. 

Specified as; a valid previously defined 

fieldname. 


OFFSET 
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indicates the bit or character position of 
the defined field on which this subfield is 
to start* 

Specified as: a positive numeric value 
tetween zero and the lenght of the defined 
field minus one. 

NOTE; the offset value must be specified if 
the subfield is specified. 


FILE 

identifies the descriptor region on which 
resides the field that is the defining base 
for this subfield. 

Specified as; 

(1) The character concatenated to the 

descriptor file region name. 

(2) The anchor file which may be entered as 

either of the followina: ANCNOP or 

gN. 

(3) An associated file which may be entered 
as either of the following; ASSOCIATED 
or SS. 

(4) A subfile which may be entered as either 
of the following; SOBFIIE or s. 

Cefault; will be assumed to be the anchor 
file, 

NOTE; this carameter only needs to be 
entered if the defined fieldname is not 
unique within the data base, such as 
PECIEN. 

FLDNAFE2 

identifies a field which is used to determine 
which associated file or which subfile is 
being referenced. 

Specified as; a valid fieldname. 

NOTE; There is a user default variable 
"EDPROWFT” which when set equal to will 

cause the user to be prompted for every 
possible applicable parameter while the user 
is either ADDinq a new field or CHANGing an 
existing field. In the normal mode there are 
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?:araraeters such as fiel<1 alignment (”ALIGN"1 
which are not prompted for if the user does 
net enter them in the command stream# 

NO’IE; Any parameter to the CHANGE function 
which is defaulted will imply that the 
existing value for that descriptor field will 
te left unaltered, 

NOTE; There is a user default variable 
"EDPRCRJ 1 •' which when set equel to "Y" will 
cause the user to be prompted for every 
possible applicable parameter while the user 
is aCD*ing or CHANGE'ing a field. In the 
normal mode, there are parameters such as 
field aliqnment, "ALIGN", which are not 
prompted for if the user does not enter them 
in the command stream. 


EXAMPtES: 

1, Xhen first creating a new set of descriptors, 
the user is first prompted for the anchor 
file hey field. 


2 , 


SYSTBB: 

USEB: 

SYSTEM: 

USER: 

SYSTEM: 

USER: 

SYSTEB: 

USER: 

SYSTEM: 

USER: 

SYSTEM; 


ENTER KEY; 

AEC ACCESSNO 
ENTER FIEILTYPE: 

A 

ENTER EIEID FCFMAT: 

F 

ENTER FIEID LENGTH: 

8 

ENTER ROUTINES: 

(return - wants standard defaults) 
ENTER: (prompt for next editing 

request) 


NOTE: If the user declines to enter the key 
field information, the Editor is terminated 
and control is returned to the Maintenance 
director. 

The user wishes to add the field USERNAME 
which is to be a varying element field, each 
element is to be 12 characters long and allow 
for 50 elements per record. USERNAME is to 
be placed on the associated file along with 
USEFTYPE, It is also to be inverted. 


SYSTEM: ENTER: 

USER: ADC 

SYSTEM: ENTER FIEID NAME: 
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USSR: OSIBNAHE 

SYSTEM: ENTER FIELD TYPE: 

CSEP: A 

SYSTEM; ENTIP FIELD FORMAT: 

USER: YE 

SYSTEM; ESTER FIELD LENGTH; 

USER; 500 

SYSTEM; ESTER EIEMEST LENGTH: 

USER; 12 

SYSTEM; ESTEP SOMBER CF ELEMENTS: 

USEE; 50 

SYSTEM; ENTER RCDTINES: 

USER: (CONV=ONCVT,FORMAT=UNFHT, 

VALID=ONVAlr) 

SYSTEM; IS FIELD TO BE INDEXED? 

USER; YES 

SYSTEM: OS WHICH INDEX FILE IS FIELD TO BE 

PLACED? 

OSER: (return) 

SYSTEM; IS FIEID TO BE ON AN ASSOCIATED 
FILE? 

USER: Y 

SYSTEM: ON NHICH ASSOCIATED FILE IS FIELD TO 

EE PLACED? 

USER; OSERTYPE 

SYSTEM; IS FIELD TO BE PLACED ON A SUBFILE? 
USER; NO 

SYSTEM; ENTER DEFINING BASE FIELD NAME; 

USER: (return) 

SYSTEM; ENTER: 

3* The user wishes to change the field length on 
field SOCSECNO froiD 8 to 9 and wishes to 
irake the index on which it appears a spanned 
index. 

SYSTEM; ENTER: 

OSER: CHANGE SOCSECNO, ,9) ,Y) ,,, , 

B. The ACCLIKE Descriptor Function 

This functicn allows the user to create a 
descriptor with all the same specifications as a 
previously defined field. 

ADDLIKE FLDNAHEl=new-fieldnaiBe, 
FlDNAME2=other-f ieldname 

Where; 

FLCNAKE1 

identifies the new descriptor to be added. 
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Specifi€d as: a valid fieldname. 

FIDWAKE2 

identifies a previously defined field of 
shich the new field is to be an exact 
duplicate except for the field name. 

Specified as: a valid field name. 

EXAMPLE: 

1. The user wishes to add field MISKEYHB to have 
exactly the santc specifications as the field 
MAaKEYWE. 

SySTEM; EWYEB: 

OSES: ADELIKE MIMKEEWD^fl A JKEYWD 

C. The CEECKPCIKT Command 

Checkpoint allows the user to save the descriptors 
currently defined in a separate TSS VAM file. 

CHEPCINl (none) 

CHKPCIKT should be used when it is deemed 
necessary to save the descriptors as rapidly 
as possible. The user may continue to 
process at a future time VIA the Restore 
Command. 

D. The CFEATESOB Command 

The command allows the user to create a subfile. 

CSEATSUE flIWAME=control-field-Dame, 
r5AypECS=#-r€cords, 

ASSCC=<Y|N>, 

AELENAME=field-naa>e 


Shere: 

FIENAKE 

identifies the field to be hnown as the 
subfile control field. 

specified as; a valid field name. 

MAXRECS 

indicates the maximum number of subfile 
records that can occur per anchor file 
record. 
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Specified as; a binary number in the range 
cf 1:1325. 


ASSOC 

indicates whether the field is to be 
associated. 

Specified as; a boolean value, 

Eefault: N 

AFtENftME 

identifies another field, previously defined, 
with which this field is to be associated. 

Specified as: a valid previously entered 

f ieldnaine. 

EXfiMPIE; 

The user wants to create a subfile for "PETS” 
which is to te associated with CHILD. 

SYSTEM: ENTEE: 

DSER; CHEATSOE PETS , 20, Y, CHILD 

E. The DELETE Cemmand 

This command allows the user to delete a 
previcQsly created field descriptor other than 
the Key field. 

EELETE FIDSAKE=fi€ldnalDe 

Where: 

FIDNAME 

identifies the field to be deleted. 

Specified as: previously described field 

name. 

F, IHE DISPLAY CCMMAfiD 

This command allows the user to display the 
specif icaticDs entered for a previously created 
descriptor, 

DISPLAY FLDNAME=fieianame 
Where: 


FIENAKE 
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iaentifies the field descriptor to be 
displayed. 

Specified as? a valid fieldnane. 

The END command 

This cofliiDand terminates a descriptor editor 
session. 

ENC (none) 

After the ENt ccmmand has finished, control i^ill 
fee returned to the Haintenance director. If the 
user has not 5TlE*d since roakinq additions, 
deletions, or modifications, he will be queried as 
to whether he wishes to FILE the descriptors. If 
the user wishes to terminate, then the descriptor 
editor will indeed terminate the current session; 
otherwise, the user will be prompted for his next 
descriptor editor command. 

The FIELDS Ccitmand 

This command allows the user to display the names 
of all the field descriptors thus far defined. 

FIELDS (none) 

The PILE Command 

This function allows the user to indicate that he 
wants the descriptors to be written from virtual 
raemctv to disk storage. 

FILE CESCCK=<7|N> 

Where : 

DESCOK 

indicates whether or not the descriptors are 
complete. If a NO value is indicated no data 
can be leaded into this file. 

Specified as; a boolean value. 

tefault; N 

The FIDSBC (Field Security) Command 

This command permits the data base owner to 
restrict access to a field or a group of fields. 
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FIDSEC FltNAPE= (field-name) , 

SECOPITY- («AED| EEIETE>.> 

security-code<, . . . >) 


Where; 

FIENAME 

is a list of one or more existing fieldnames 
to which the data base owner wishes to 
restrict access* 

Specified as; a list of valid fieldnames. 
SECnPITY 

is a list of security codes appended by an 
add-delete code separated from the security 
code by a period. The add-delete code is 
specified as A or ADD for adding a security 
code and D or DELETE for deleting a security 
code. If no add-delete code is entered, it 
is assumed the user is adding the security 
code. The security code is specified as an 
alphanumeric character string of 1 to 8 
characters. A maximum of 18 security codes 
cay be specified for any field. 


EXAPIPIE: 

The data base owner wishes to restrict the 
fields ACCCDNT and VAlOE to the persons with 
the security codes BOB, HARPY, and JOHP and 
to delete TOM from the security list. 

SYSTEf: ENTEEt 

DSER; FLDSEC (ACCOUNT, VAIOE) , (ADD. BOB, 

R.HAPBY,A. JOHN,D.TOH) 


The MCVE Command 

This command allows the user to reposition fields 
within the defined data layout. 

MOVE FLEN AM E1=new- location- fieldname, 

FID NAME 2=fieldname 


Where; 

FLCNAEE1 

identifies which field or the new location 
after which the field specified bv FLDNAME2 
is to be positioned* 

Specified as: a valid fieldname. 
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PIDKA!?E2 

identifies the field to be moved. 

Specified as; a valid fieldname. 

flOTE: A redefined field, i,e., snbfield, 

cannot be moved as its position is determined 
by the position of the base field. If a 
sufcfield is specified as the new position 
fieldname, the WOVE command will locate and 
use the fcase field name as the new position 
field name, 

NOTE; A superfield cannot be used as a new 
position fieldname, nor can it be moved, as 
a superfield consisting only of other fields 
has nc field position, 

EXAMPLE: 

The user has entered the three fixed fields 
in the following: AFEACODE, lOCALtJDH, 

fXCHNG The user wishes to chanoe the order to 
AFEACODE, EXCHNG, lOCALNDH. 

SYSTEM; ENTEF: 

USER: HOVE AFEACODE, EXCHNG 

Notice this could also be accomplished by the 
following; 

SYSTEM; ENTER: 

DSEF; MOVE EXCHNG, lOCAINUM 
L, The PFINT Command 

This command Generates a printer listing of all 
the field descriptors and file descriptors as they 
exist in core at the time the PRINT was issued, 

PRINT (none) 

H, The RENAME Ccmmand 

This command permits the user to change the name 
of a field without altering any of its other 
specifications or its location in the data 
record. 

RENAME EIDNAHE 1=new-f ieldname, 
FlDNAME2=old-fieldname 


Where; 
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FtENAHEI 

identifies the new field naae. 

Specified as^ a valid fieldname, 

FLEfIARE2 

identifies the existing field name 

Specified as? a valid fieldname, 

EXAWPtE: The user wishes to change the name of the 
field CIEHABE to the name NEWNAME. 

SYSTEH; EKTEE: 

USER; RENABE NE«NAME,01DSABE 

The RECSEC fBecord Secarity) Command 

This command permits the user to control access to 
a group or groups cf records within the data 
base. 

FECSEC nElCNAHF^field-name, 

SECUR1TY= («A DD | DELETE> . > 

secaritycode:mask<, • . • >) 


Hhere; 

DFLCNAME 

is the existing fieldname to which the file 
record secarity is to apply. 

Specified as: a valid fieldname. 

SECURITY 

is a list of up to 18 security cedes and 
security masXs determining who is to be 
permitted access to the secured records on 
the file. It is specified as an add-delete 
code followed by a period, followed by the 
security code, followed by a colon, followed 
ty the security maslc. The add-delete code is 
specified as AED or A for adding a security 
code, or DELETE or D for deleting a security 
code. The security code is an alphanumeric 
character string cf 1-8 characters. The mask 
is two dicrit hexadecimal code. 

The security code is used to compare against 
the value in the record security field of a 
record to determine whether or not a user has 
access to that record. 
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The BHSTOBE Comoand 

This copinand permits the user to restore to 
virtual meffiocy the descriptors which had been 
previously saved by the use of the CHKPOIST 
conunand. 

FESTORE fnone) 

The SflVSTFT fSave Strategy) Command 

This command allows saving of descriptor editor 
commands in the strategy data set for future 
recreation of descriptors as they existed in 
virtual memory when the SAVSTSAT command was 
issued* 

SAVSTBT STRTNAME=strategy-'name 


Where: 

STRTKAWE 

is the strategy name in the strategy data set 
in which the descriptor editor commands are 
to b€ saved* 

Specified as: a 1-16 character long 

alphanuireric character string* 

the Superfld (Define Superfield) Command 

This command allows the user to create a new field 
descriptor which is defined as consisting of Data 
from several fields* 

SOPERFLD FLDNAME=fieldnamer 

FCCtI WE S=FCEHAT= formatting-routine, 
FIDI1ST= («INTERN AH EXTERN AL>*> 
f ield-name<, • . . >) 


Where: 


FIDNAKE 

identifies the name of the new superfield* 
Specified as: a valid field name. 


FORMAT 

identifies the routine used to format the 
data for output from the data base* 

Specified as: a routine name* 
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FLELIST 

is a list of the previouslv defined 
fieldnames from ehich this superfield is to 
te composed# The order of the fieldnames 
used to define the superfield is the order in 
uhich they vere entered* The user may 
specify whether the internal or external form 
of the field is to he passed to the 
superfield formatting routine. 

Specified as: a list of up to 16 character 

strings of the form: The output format 

concatenated to a period concatenated to the 
fieldname to be included in the soperfield. 
The format type internal may be specified 
as: 

INTEBNAI or I 

The format type external may be specified 
as: 

EXIEBNAI or E 

Cefault: If the output format is omitted, 

then it will be assumed to be the external 
format type* 

NOTE: The soperfield components must stay within 

the fcllowinq restrictions: 

1# It may contain at most one multi-element 
field. 

2. It may contain components from one but not 
more than one subfile. 

THE OPDATE MODE CCSHASDS 

A, The CHANGE CCMHAND 

This command allows the user to modify a 
previously defined field. 

CHANGE ELENAnE=fieldname, 

TYPE=<FLDTYPE=field-type 

<,A1IGN=<BIGHT! LEET>>) , 

FOFH= (FLDFOBM=f ield-format, 

F1I)1EN= field-length, 

EtEHLEN^element- length, 

EIE fill element-number 
<,DNIOns=<Y|N») , 

FODTINE= (CCNV=conversion-routine, 
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FOB HfiT=f or mattinq -routine, 

V A tID=vali<1ation- routine , 
VALID ABG=validation-arguifl€nt) 


Where: 

FlENflKE 

identifies the field to be modified. 

Specified as: a valid fieldnaiue. 

FLETYPE 

identifies the physical format of the 

field. 

Specified as: 

A fcr an alphanumeric character string, of 
which each character may consist of any 
valid EBCDIC character. 

B for a bit strinq. 

BN for an 8 bit unsigned binary number 
which has a value in the range 0-255. 

BP for a packed bit string the same as B, 
except that these fields aill be placed 
immediately after the key field as one 
continuous bit string* 

HX for a strinq of hexadecimal numbers. 

IN for numeric or a 32 bit signed binary 
number* 

S for scientific or 14 digit decimal 
number within the range of 1C**-75 : 

10**+75. 

SD for scaled decimal nine digit number 
within the range of 10**-9 ; 10**+9. 

SN for numeric or 16 bit signed binarv 
number* 

SS for short scientific or a six digit 
decimal number within the range of 
10**-75 : 10**+75. 

ALIGN 

identifies either right or left alignment of 

the field* 
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Specified as: BIGHT or B for right alignment 

and LIJT or I for left alignment, 

FIDFOBH 

identifies the logical format of the field. 

Specified as: F for FIXED,? for VABIABLE,FE, 

for FIXED EIEKENT,VE, for VARIAEIE EIEMEBT. 

FLDIEN 

indicates the length of fixed fields or the 
maximuiD length for other types of fields. 

Specified as: a positive inteaer, 

(1) For the anchor file key field, the 
maximum field length is 256. 

(2> For all other fields: 


(a) 

If 

FLDFORM=F, 

then 

the 

maximum 

field length 

is 3996 

minus 

the key 


field length; 

otherwise. 


(b) 

For 

all other 

values 

of PLDFOBa, 

the 

maximum length is 

3994 

minus 


the 

key field 

length. 

This 

allows 


for 

a two 

byte 

field 

length 


indicator. 





ELEWLEB 

indicates the length of fixed elements or the 
iraximum length for variable elements. 

Specified as: a positive numeric value vith 

the range of 1-256 if FLDFOSH is FE, else the 
range is 1-255 if FLDFCBH is ?E, This allows 
one byte for an element length indicator, 

ELEPILIM 

indicates the maximum number of elements 
allowed in the field. 

Specified as: a positive integer. 

(1) If F1DF0FM=FE, then the maximum number 
of elements is equal to the field 
length, 

(21 If FLDFCBW^VI, then the maximum number 
cf elements is the field length divided 
by two. 
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UNIODE 

indicates whether or not all element values 
within a multi-element are to be unique. 

Specified as: a boolean value. 


CONV 

identifies the name of the routine used to 
convert the input data as it is placed into 
the data base. 

Specified as: a routine name. 

FOBHAT 

identifies the routine used to format the 
data for output from the data base. 

Specified as; a routine name. 


VALID 

identifies the name of the routine used to 
validate the input data. 

Specified as: a routine name. 

VALIDABG 

indicates the arqument required by the 
validation routine to validate the input 
values. 

Specified as: a hexadecimal character strinq 

cf 1-100 characters. 

NOTE; In the DPDATE mode, values to the CHANGE 
function will not be accepted which cause changes 
to be made to ether field descriptor records, such 
as changing the field length if the field format 
is fixed as this changes the base length of the 
data records. 

NOTE: Any parameter to the CHANGE function which 

is defaulted, will imply that the existing value 
for that descriptor field will be left 
unaltered. 

Note; There is a user dafault veriable "EDPHOMPT” 
which when set equal to *'Y” will cause the user to 
be prompted fer every possible applicable 
parameter while the user is CHANGE*ing an existing 
field. In the normal mode there are parameters 
such as field alignment <”A1IGN”) which are not 
prompted for if the user does not enter them in 
the command stream. 



PAGE 131 


EXAKPIE; 

The user wishes to change the specifications 
for the field PEOPLE to FIGHT aligniaent, 
change the element length from 20 to 30 and 
the element limit from 5 to 10. 

EYSTEH: ENTEB: 

USER: CHANGE PEOPLE, (, RIGHT) ,30 , 1 0) , , 

The DISPLAY CCHMAND 

This command allows the user to display the 
specif icaticns entered for a previously created 
descriptor* 

EISPLAY ElCNAKE=fieianaiT!e 
Where: 

FLDNAME 

identifies the field descriptor to he 
displayed* 

Specified as: a valid fieldname* 

The END CCKBAKD 

The END command is terminates a descriptor editor 
sessicn 

END (none) 

After the END command has finished, control will 
be returned tc the Maintenance Director. 

The FIELDS Ccmmand; displays all of the descriptor 
fieldnames in the descriptor file record, and all 
of the descriptor fieldnames in a field 
descriptor* 

FIELDS (none) 

FLDSEC (Field Security) Command: permits the file 
owner to restrict access to a field, 

FLDSEC FLCNAHE=field-name, 

SECURITY^ («ADD|DELETE>.> 

securitv-code<, * . *>) 


FLDNAEE 

is an existing field name to which the owner 
wishes to restrict access* 
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Specified as: a valid fieldname. 

SECORITY 

is a list of security codes appended by an 
add-delete code separated from the security 
code by a period. The add-delete code is 
specified as A or ADD for adding a security 
code and D or DELETE for deleting a security 
code. If no add-delete code is entered, it 
is assumed the user is adding the security 
code. The security code is specified as an 
alphanumeric character string of 1 to 8 
characters. A maximum of 18 security codes 
ray be specified for any field. 

The PATCH Command 

This command is used to change the value of almost 
any descriptor field cn any descriptor record in 
any descriptor region. To use the PATCH command, 
the user must do a RE7IEH of the desired 

descriptor record. This not onlv displays the 
contents of this descriptor but also positions to 
the reccrd that is to be patched. 

PATCH (keyword-text<, . . . >) 

Where : 

heyvord 

identifies the descriptor field that is to be 
patched. 

text 

is the value with which the descriptor field 
specified in * keyword* is to be patched. 

The user may specify any number of patches in a 
parenthesized list. 

The following is a list of file descriptor or 
header descriptor field names that may be patched 
and their values. 


HEACEH FIEICNABE FIELD VALDES 


<1) 

FIIBTYPE 

ANCHOR or 

1, ASSOCIATE or 2, 



SDEFILE or 

3, INDEX or 4. 

(2) 

EESCRCT 

A 

positive 

integer <= 4000. 

(3) 

ESELNGTH 

A 

positive 

integer <= 4000. 

(4) 

tESCOK 

A 

boolean 

value. 

(5) 

SPASNED 

A 

boolean 

value* 

(6) 

DATA 

A 

boolean 

value. 
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(7) 

ENTNAEIE 

A boolean value. 

(8) 

HNTNING 

A boolean value. 

m 

rOADAELE 

A boolean value. 

no) 

REMAINS 

A hexadecimal character string 
in the range of OCOOOCO to 
FFFFFFFF. 

(11) 

BECSECFP 

A positive integer <= 261. 

(12) 

BSECTYCD 

The form of the patch text is: 
(n) security-code: mask 


Where: 


is the index of the security code to be 
patched. The inden must be entered or the 
patch will te rejected. 

Specified as: a positive integer <= 18. 

NOTE: The next security code value may be 

added to the list by specifying the next 
larger index value. 

Refer to the HECSEC command writeup for a 
discussion of the security parameter. 

SXAHPIE: 


The user wishes to patch the anchor header 
descriptor so that BSE1NGTH=31, DATA=HO, and 
the second value of record security to 
E0B:60. 


SYSTEH: 

USER: 

SYSTEH: 

SYSTEM: 

USER: 

SYSTEE: 


ENTER 

REVIEW * »,*HZADER 
(displays the anchor header 
information. ) 

ENTER: 

PATCH (BSELNGTH=31,DATA=Nr 
RSECTYCE-(2) BOB: 60) 

ENTER 


The following is a list of field descriptor 
fieldnames that may be patched along with their 
values. 


FIELD DESCRIPTOR 

FTELDNABES FIELD VALDES 


(1) ASSOCFIl 


a one character string in the 
range *G* to *9* • 
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(2) 

SOEPIIE 

a one character string in the 
range *Q* to 

(3) 

IN7FT1E 

a one character string in the 
range *A* to *P* • 

w 

EEADCNIY 

a boolean value. 

(5) 

SDBCSTBt 

a boolean value. 

(6) 

VfiEFLC 

VARYING or V, FIXED or F. 

(7) 

PTTFLD 

a boolean value. 

(8) 

KOMALTGtJ 

BIGHT or B,LEFT or L, 

(9) 

VARBIl 

VABYING or V, FIXED or F. 

(10) 

TlNlQOEtT 

a boolean value. 

(11) 

INDEXEXT 

EXTEBNAI or E, INTERNAL or I. 

(12) 

GENEPCBT 

a routine name. 

(13) 

VALIDBTN 

a routine name. 

(14) 

EEFOBKAT 

a routine name. 

(15) 

SPAKE 

a hexadecimal character 
string in the tanoe of 
COOOOOCCOOOOOOOO to 
FFFFFFIFFFFFFFFF. 

(16) 

FLDPOSIT 

a positive integer <= 4000. 

(17) 

FLDIES 

a positive integer. If the 
field is a single element and 
indexed then the maximum value 
is 256. Otherwise the maximum 
value is 4000. 

(18) 

DFIDLEN 

a positive integer. If the 
field is a single element and 
indexed then the maximum value 
is 256. Otherwise the maximum 
value is 4000. 

(19) 

EITLIH 

a positive integer. If the 


elements are fixed lenqth, the 
maximum value is 4000. 
Otherwise the maximum value is 
2C00. 
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a positive inteqer* If the 
elements are fixed length, 
the nsaxiraam value is 4000. 
Otherwise the maxinuro value is 
2000 . 

a positive integer <“ 256. 

a positive integer <= 256. 

a hexadecimal character string 
of length 1 to 100 
characters. 

The patch text is of the 

form: 

(n> «INTEBNAI| EXTEaNftI>.>fieldinaiBe 
Where; 
n 

is the index of the 

superfield component to 
be patched. 

Specified as; a positive 
integer <= 16. 

NOTE; The index mast be 
entered or the patch will 
be rejected* 

Befer to the SUPEBFID 
command writeup for the 
super fie Id components 
description. 

(25) SECOPITY The patch is in the form: 

(n) security-code 

Where; 

n 

is the index of the 
security code to be 
patched. 

Specified as; a positive 
integer <= 18. 

NOTE; The index must be 


(20) EELTLIR 

(21) EITLEN 

(22) DELTLEN 

(23) VALIDRBG 

(24) KAMEFti: 
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entered or the patch will 
be reiected. 

security-code 

is an alphanumeric 

character string of 
length 1 to 8 

characters. 


EXAMPlEt 

The user wishes to patch the field PHONEHUM 
cn associate file 1 to have a formatting 
routine of FHCNFHT on the third component of 
this superfield to te in external form and 
have the field name of lOCAtNtJM, 


SYSTEM: EPTEB; 

OSER: REVIEW 1,PH0NES0M 

SYSTEM: (displays the field information.) 

SYSTEM: ENTER: 

DSER: PATCH (RErORBAT=PHONPKT, 

NAMEFLD=(3) E.IOCAINDH) 

SYSTEM: ENTER: 


The RICSEC (RECORD SECURITY) COMMAND 

This command permits the owner to control access 
to a group or groups of records* 

EECSEC DFIDKAME=field-name, 

SECURITY= («ADD)DEIETB>.> 

security-code<r • . . >) 

Where : 

DFIDHAME 

is an existing fieldname which is used to 
define which file record security is to 

apply* 

Specified as: a valid fieldname. 

SECURITY 

is a list of up to 18 security codes and 
security masks determining who is to be 
permitted access to the file* It is 
specified as an add-delete code, followed by 
a period, followed by the security code, 
followed by a colon, followed by the security 
mask* The add-delete code is specified as 
ADD or A for adding a security code, or 
CEIETE or D for deleting a security code* 
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Ihe security code is an alphanumeric 
character string of 1-8 characters. The mask 
is a two dioit hexadecimal code. 

The security code is used to compare against 
the value in the record security field of a 
record to determine whether or not a user has 
access to that record. 

NOTE: In the OPDATE mode the record security must 
already exist for the file to be ahle to use 
RECSEC. In the UPDATE mode, RECSEC is used to 
update the existing list of record security codes 
and masks. 

The REVIEW CCKMAND 

This command is used to review the contents of any 
descriptor record cn any descriptor file. This 
includes dummy records, file descriptor records 
and those records such as RECLEN which are not 
unique to the entire data base, 

REVIEW fIlE=f ile-name, 

FlDNAP!E-<*HEADER|field-name> 


Where: 


PIIE 

identifies the descriptor region containing 
the fieldname to be reviewed. 

Specified as: the full descriptor region 

name or the character suffix of the 
descriptor region • 

ROTE: A null value is taken to indicate the 

anchor region, 

FIDNAKE 

identifies the field which is to be 

reviewed. 

Soecified as: a valid fieldname or either of 

the following character strings: *HEADER or 

♦ which will imply a review of the file 
descriptor for the descriptor region named 
above. 
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APPENDIX A. 

A* Descriptor Editor cooisand format, 

1, Edit Eescriptcr. 

EDIT MODE ^ <CREATE|0PtATEtEESTOPE> 

B« Create f^ode command formats* 

1. ACE FICNAKI=f ield-name, 

TYPE= <FLETYPE=f ield-type 

<,A1IGN=<RIGHT| IEFT>) , 

FOBH= (FIE EOFM=fi€ld- format, 

FrctE»= field-length, 

ELE«LEH=el e men t- length, 
ElEWtin=€leiBent -number 
<,ONIOOE=<Y|N») , 

EOOTINE£= (CCNV=con version-routine, 

FOPNAT^f or mat ting- routine, 

VA1ID= validation-routine, 
VALlCAPG=validation-argQment) , 
INDEXED= (INDEX=<y I N> , 

IFLDN AM field-name 
<,EXTINT = <INTEPNAL I EXTERN AI>, 
EXTLEN*external-lengtb, 
SPANNBD=<Y|N») , 

ASSOCED* (ASSCC«<Y| N>, 

AFlENAMEsfield-name) , 

SDBFIIED= (STJBFILiXY^ N>, 

SFlDNAME-field-name) , 

SUB?IELD= (SDEF1D=<Y| N>,BASEF1D=FIEIENAME, 
OFFSET^offset 

<,<FILE-<*filename1 ANCflOR>> 
or <FILE=<ASSOCIATED|SOBFIIE>, 
FID NAME 2=field-name») 

2* ADDLIKE FIDNAFE=new fieldname, 

FlDHAME2=otfcer-fieldname 

3, CHANGE FLCNAME=fi€ld-name, 

TYPE= (FLDTYPE=field-type 

<,ALIGN=RIGHTiLEFT») , 

FORR= (FLDFCBB=f ield-f ormat, 
FLDtEN^field-lengtb, 
ELEHLEK-eleiaent-length, 
ELEHLin=€lement- number 
<,UKIGDE=<Y1N») , 

BOUTIN ES= (CONV=conversion-routine, 

FOP MAT= formatting-routine, 
VALID= validation- ton tine , 
VALIDAEG=validation-araument) , 
INDEXEE=(INDEX=<Y|N>, 
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IFLENAME=fi6ia-naDie 
<,EXTINT=<INTERNAH EXTEENAL>, 
EXTLEN=external-lenqth, 
SPAKWED=<Y|N») , 

ASSOCEE= (ASSOC-<Y| N>, 

APtDNAME=field-name) ^ 

SOEIItED= «StIBFIlE=<Yl N>, 

SFIDNAME=fieXa-name) , 

STJBFIEID= (BASEFlT)=f ield-name, 

SUBfIElD= (S0BFLD=<7TN>,BASEFtB=FIElDNABE 
CFFSET=of fset 

<,<FTIE=<*filena[ne| ABCHOB» 
or <FILE=<ASSOCIATED|S0BFILE>, 
FL1DNAME2= field- naiJie>>) 


4. CBKPOINT (none) 


5. CEE AT SOB FlENA3E=control-f ield-na»e, 

HA XPECS=#- records^ 

ASSOC=<Y| N>, 

AFLBAHE= field-name 


6, DELETE FLENAHE*f ield-name 

7. DISPLAY FLENAME=field-naae 
8* END (none) 

9. FIELDS (none) 

10. FILE EESCOK=<Y|n> 

11. FLESEC FLESAHE=(field-nanie<,...>) , 

SECDFITY= («AEDt EEIETE>. > 

security-code<, . • . >) 

12. MOVE EXDNAHE 1=new-location-f ield-name , 

FID NAHE2= field -name 


13. PFINT (none) 


14. BECSEC DFLDNAME=f ield-name. 
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SECUfiITY= («AEDtDEI'ETE>.> 

sec urity -code :in ask <, • • * >) 


15, RENAME FLENA«E1=new-f ield-name, 
FLERA)1E2=old-f ieldnaitie 


16. RESTORE (none) 


17. SAVSTRT STBTNAME=Strateqy-na[D€ 


18. SUPER RLE FXERRME=f ield-namer 

ROOTIRES= (CO NV^con version-routine, 

FORMAT=fotmattinq-rout ine, 

V All D= validation -routine, 
VALlDASG^validation-arqument) , 
FLDIIST= («INTEPNAli EXTERN AL>. > 
f ield-name<, . • • >) 

UPDATE BODE Comoand Formats. 


1. CHANGE FLCHAME*field-natie, 

TYPB= (FLDTYPE=fieia-type 

<,ALIGN*<BIGHTjlEFT») , 

EORK= (FLDFGSM-field-forinat, 
FLDLEN-field-lenqth, 
ELEMLEN=element-lenqth, 
ELEHlIM=€lement-n umber, 
<,ONIQDE=<X|n») , 

ROUTINES^ (CCNV^con version -routine, 

FORM AT^f or matting-routine, 

V A II D= validation -routine, 
VALID AEG- validation-argument) 


2. DISPLAY FLENAME*field-naiDe 

3. END (none) 

4. FIELDS (none) 

5. FLDSEC FLENAME=field-name, 

SECBRITY= («AED|DELETE>.> 

security-code<, , . . >) 



PA^CH ffield-naine= value <,...>) 


BECSEC DFIDNARE=fieia-name, 

SECORITY= («ADD I DEIETS> .> 

SGctiri tv-code ;Toask<, 


EIIE=f ile-name , 
JLDNAMf=<*BEAEEB I FIELD-nanie> 


BEVIER 
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APPENDIX B. 

CPEATE NODE 
OPEPAND RELATIONSHIPS 

When creating descriptors there are certain implied 
relationships between the various operand combinations that 
may be specified. In those cases, the Descriptor Editor 
assumes the implied value and over-rides any value specified 
by the user. When modifying descriptors the Descriptor 
Editor normally interprets a default response to indicate no 
change to a particular operand. 

The following table indicates the default values and the 
Esaximum values for several parameters of the ADD command. 



TABLE 1 


CREATE MODE 

OPERAND DEFAULT AND MAXIMUM VALUES 


FLDTYPE 

FLDFMT 

DEFAULT 

ALIGNMENT 

MAXIMUM 

FLDLEN 

MAXIMUM 

ELEMLEN 

MAXIMUM 

ELEMLIM 

A 

F 

L 

3996-Key Length 

NA 

NA 

A 

V 

L 

3994-Key Length 

NA 

NA 

A 

FE 

L 

3994-Key Length 

256 

(FLDLEN) 

A 

VE 

L 

3994-Key Length 

255 

(FLDLEN/2) 

B 

F 

L 

1 

NA 

NA 

BN 

F 

R 

1 

NA 

NA 

BN 

FE 

R 

3994-Key Length 

1 

(FLDLEN) 

BP 

F 

L 

1 

NA 

NA 

HX 

F 

L 

2 (3996-Key Length) 

NA 

NA 

HX 

V 

L 

2 (3994-Key Length) 

NA 

NA 

HX 

FE 

L 

2 (3994-Key Length) 

256 

(FLDLEN) 

HX 

VE 

L 

2 (3994-Key Length) 

255 

(FLDLEN/2) 

LN 

F 

R 

4 

NA 

NA 

LN 

FE 

R 

3994-Key Length 

4 

(FLDLEN/4) 

S 

F 

R 

8 

NA 

NA 

S 

FE 

R 

3994-Key Length 

8 

(FLDLEN/ 8) 

5D 

F 

R 

5 

NA 

' NA 

SD 

FE 

R 

3994-Key Length 

5 

(FLDLEN/5) 

SN 

F 

R 

2 

NA 

NA 

SN 

FE 

R 

3994-Key Length 

2 

(FLDLEN/2) 

SS 

F 

R 

4 

NA 

NA 

SS 

FE 

R 

3994-Key Length 

4 

(FLDLEN/4) 


(1) Default conversion and formatting routine names are 
inserted by the editor unless specified by the user. 
The routine names have the format DBXXXYY, where; 

"XXX" is either CVT for conversion routine or FMT 
for a formatting routine, and 

"YY" is "SP" for field type "A" and is the field 
type itself for all other field types. 
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APPEHDIX C* 

PKEEEIINEE PIELDS 

In most cases when the user defines or creates a nev 
fieldname there is only one field descriptor created. There 
are^ however, some exceptions to this which are enumerated 
below. 

When the anchor file Jcey field is completely defined by the 
user, the follcwino fields are automatically defined and 
added to the list of field descriptors, 

1. The FILEKEY field is a field defined over the anchor 
file key field. This field has all of the 
characteristics of the anchor file key field except for 
the field name and that it is a readonly field, that is 
a redefined field* 

2. The fields F5EEF0BW and COMMENTS are defined for the 
retrieval system COMMENTS is a varying length field 
designed to hold any comment the user may wish to place 
there. FPEEFORM will allow the user to specify his own 
particular keywords for the file he is referencing and 
he is able to base strategies on these user entered 
keywords. 

The EECLEN is a predefine field which will appear in each 
descriptor region of the data base. This field defines the 
record length field which appears on each variable length 
record in a file. 

Rhen the user specifies record security for any file, for 
the first time, a field is created describing the record 
security code that appears in each data record of that file. 
This field is placed immediately after the anchor key for 
the anchor and associated files, and immediately after the 
parent kev field on sutfiles. 

The record security fieldname is created in the following 
manner for the different file types: 

1. ANCHOR file - the fieldname is BECSEC. 

2. ASSOCIATEE file - the fieldname is BECSEC concatenated 
to the suffix of the associated file, i.e. 1 to 9. 

3. SUBFILE - the fieldname is the subfile control 
fieldname concatenated to RS. 

Rhen the user creates a subfile by the CPEATSUB command the 
following fields are defined: 
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1* The subfile ccntrcl field itself which resides either 
on the anchor file or an associated file, 

2* The subfile ke^ field which is the subfile control 

field nanie concatenated, to ID, 

3* The subfile parent key field which is a copy of the 
parent anchor key field. This fieldname is created by 
takinq the subfile control fieldname concatenated with 
PK. 

4* Allowance is made for subfile record security by 

creatinq the fieldname of subfile control field name 
concatenated to RS, 

The field characteristics of each of the predefined fields 
are included in Table 2, 

All of the af creraentioned fieldnames are included in a 
reserved list. These fields cannot be altered by the user 
except in the following manner: 

To modify FItEKEY, the anchor file key field must be 
modified. The predefined fieldnames for record 
security cannot be modified in any way and can only be 
created through use of the SECSEC command. The HECLBN 
field descriptor cannot be modified. The subfile 
control field and subfile key field cannot be modified 
once created. The subfile parent key field will only 
be changed to reflect changes in the anchor file key 
field. The fieldname for subfile record security can 
only be created through use of the PECSEC command* 

Table 3 contains the names cf the reserved fieldnames. 
As subfiles are created, the subfile control fieldname, 
the subfile key fieldname, the subfile parent kev field 
name, and the subfile record security fieldname are 
placed in the reserved fieldname table, which then 
become reserved field names subject to the above listed 
restrictions. 



TABLE 2 


PREDEFINED FIELD CHARACTERISTICS 

record^^^ subfile^^^ subfile^^^ subfile^^^ 


FLDNAME 

COMMENTS 

FILEKEY 

FREEFORM 

RECLEN 

security 

control 

id 

parent 

ASSOCFIL 

1 

(none) 

1 

(none) 

(none) 

(5) 

(none) 

(none) 

SUBFILE 

(none) 

(none) 

(none) 

(none) 

(none) 

(none) 

(none) 

(none) 

INVFILE 

(none) 

(none) 

A 

(none) 

(none) 

(none) 

(none) 

(none) 

READONLY 

NO 

Y 

NO 

YES 

NO 

YES 

NO 

YES 

SUBCNTRL 

NO 

N 

NO 

NO 

NO 

YES 

NO 

NO 

VARFLD 

VARYING 

F 

VARYING 

FIXED 

FIXED 

VARYING 

FIXED 

FIXED 

BITFLD 

NO 

N 

NO 

NO 

NO 

NO 

NO 

NO 

NUMALIGN 

LEFT 

(2) 

LEFT 

RIGHT 

LEFT 

RIGHT 

RIGHT 

(2) 

VARELT 

(none) 

(none) 

FIXED 

(none) 

(none) 

FIXED 

(none) 

(none) 

UNIQUELT 

NO 

(none) 

NO 

(none) 

(none) 

YES 

(none) 

(none) 

INDEXEXT 

(none) 

(none) 

INTERNAL 

(none) 

(none) 

(none) 

(none) 

(none) 

GENERCRT 

DBCVTSB 

(2) 

DBCVTSB 

DBCVTRL 

DBCVTHX 

DBCVTID 

DBCVTID 

(2) 

VALIDRTN 

(none) 

(2) 

(none) 

(none) 

(none) 

(none) 

(none) 

(2) 

REFORMAT 

DBFMTSB 

(2) 

DBFMTSB 

DBFMTRL 

DBFMTHX 

DBFMTID 

DBFMTID 

(2) 

FLDPOSIT 

2 

4 

1 

0 

(4) 

(4) 

4 

7 

FLDLEN 

3988 

(2) 

3988 

4 

1 

(6) 

3 

(2) 

ELTLIM 

0 

0 

100 

0 

0 

(6) 

0 

0 

ELTLEN 

0 

0 

40 

0 

0 

3 

0 

0 

VALIDARG 

(none) 

(2) 

(none) 

(none) 

(none) 

(none) 

(none) 

(2) 

NAMEFLD 

(none) (none) (none) 

(none). . 

(none) 

(none). . 

(none),^. 

(none). 

SECURITY 

(none)^'^'^ (none)^'^'^ (none)^ ^ 

(none)^ ^ 

(none)^ * 

(none)'^'*'' 

(none)<3> 

(none) 

(1) 

Refer to 

the text 

for the derivation of the actual fieldname. 


(2) 

The actual value is taken from the anchor key field. 



(3) 

There is 

no field 

security on these fields unless specified by the 



user through use of the FLDSEC command 

1 . 




(4) 

The value will be 

determined 

at "FILE" 

' time. 




(5) 

The value will depend on the 

"ASSOC" and "AFLDNAME" parameter values 



to the CREATSUB command. 






(6) 

The actual value will depend 

on the input value to "MAXRECS’ 

' parameter 



to the CREATSUB command. 
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&PPENEIX D. 

DESCEIPTCB FIIE OVEPVIEW 

Each descriptor fils is a virtual indexed sequential (VISAi^) 
region Data Set where the tey is developed by concatenating 
an eight character field name to a seven character file 
name. The name of tie descriptor file is constructed by 
appending a ”1” to the six-character data base name (padded 
with if necessary) ♦ 

The first record of each set of descriptors is called a 
header record and has a field name of blanks. This record 
is used by the system to reflect the current status and 
level of activity of that file, as well as controlling 
access to it, and is composed of fields described in Table 
4. The remaining records are the field descriptors, 
themselves, and are cctrposed of the fields described in 
Table 5. 



/¥f 


TABLE 3 


PREDEFINED RESERVED FIELDNAMES 


1. COMMENTS 

2. FILEKEY 

3. FREEWORD 

4. RECLEN 

5. RECSEG 

6. RECSECl 

7. RECSEC2 

8. RECSEC3 

9. RECSEC4 

10. RECSEC5 

11. RECSEC6 

12. RECSEC7 

13. RECSEC8 

14. RECSEC9 



TABLE 4 


FILE DESCRIPTOR FIELD SPECIFICATION 


FIELD NAME 

FIELD 

TYPE 

FIELD 

FORMAT 

FIELD 

LOCATION 

FIELD 

LENGTH 

ELEMENT 

LENGTH 

ELEMENT 

COUNT 

RECLEN 

LN 

F 

0 

4 

0 

0 

KEY 

A 

F 

4 

15 

0 

0 

FLENAME 

A 

F 

4 

7 

0 

0 

DATAPLEX 

A 

F 

■4 

6 

0 

0 

SUFFIX 

A 

F 

10 

1 

0 

0 

FLDNAME 

A 

F 

11 

8 

0 

0 

FILETYPE 

A 

F 

19 

1 

0 

0 

DESCRCT 

SN 

F 

20 

2 

0 

0 

BSELNGTH 

SN 

F 

22 

2 

0 

0 

DESCOK 

B 

F 

24 

0(1) 

0 

0 

SPANNED 

B 

F 

24 

2(1) 

0 

0 

DATA 

B 

F 

24 

4(1) 

0 

0 

MNTNABLE 

B 

F 

24 

6(1) 

0 

0 

MNTNING 

B 

F 

25 

0(1) 

0 

0 

LOADABLE 

B 

F 

25 

4(1) 

0 

0 

REMAINS 

HX 

F 

26 

4 

0 

0 

RECSECFP 

SN 

F 

30 

2 

0 

0 

RSECTYCD 

A 

FE 

1(2) 

164 

9 

18 

(1) 

For bit switches the length field is 
the bit location within the byte. 

used to indicate 


(2) 

For variable 

length fields the location field is 

used 



as a variable field index. 



TABLE 5 


FIELD DESCRIPTOR FIELD SPECIFICATION 


field name 

FIELD 

TYPE 

FIELD 

FORMAT 

FIELD 

LOCATION 

FIELD 

LENGTH 

ELEMENT 

LENGTH 

ELEMENT 

COUNT 

RECLEN 

LN 

F 

0 

4 

0 

0 

KEY 

A 

F 

4 

15 

0 

0 

flename 

A 

F 

4 

7 

0 

0 

DATAPLEX 

A 

F 

4 

6 

0 

0 

SUFFIX 

A 

F 

10 

1 

0 

0 

FLDNAME 

A 

F 

11 

8 

0 

0 

ASSOCFIL 

A 

F 

19 

1 

0 

0 

SUBFILE 

A 

F 

20 

1 

0 

0 

INVFILE 

A 

F 

21 

1 

0 

0 

READONLY 

B 

F 

22 

0(1) 

0 

0 

SUBCNTRL 

B 

F 

22 

2(1) 

0 

0 

VARFLD 

B 

F 

22 

4(1) 

0 

0 

BITFLD 

B 

F 

22 

6(1) 

0 

0 

numalign 

B 

F 

23 

0(1) 

0 

0 

VARELT 

B 

F 

23 

2(1) 

0 

0 

UNIQUELT 

B 

F 

23 

4(1) 

0 

0 

INDEXEXT 

B 

F 

23 

6(1) 

0 

0 

GENERCRT 

A 

F 

24 

8 

0 

0 

VALIDRTN 

A 

F 

32 

8 

0 

0 

REFORMAT 

A 

F 

40' 

8 

0 

0 

SPARE 

HX 

F 

48 

8 

0 

0 

NAMECNT 

SN 

F 

56 

2 

0 

0 

FLDPOSIT 

SN 

F 

58 

2 

0 

0 

FLDLEN 

SN 

F 

60 

2 

0 

0 

DFLDLEN 

SN 

F 

62 

2 

0 

0 

ELTLIM 

SN 

F 

64 

2 

0 

0 

DELTLIM 

SN 

F 

66 

2 

0 

0 

ELTLEN 

SN 

F 

68 

2 

0 

0 

DELTLEN 

SN 

F 

70 

2 

0 

0 

VALIDARG 

A 

V 

1(2) 

52 

0 

0 

NAMEFLD 

A 

FE 

2(2) 

146 

8 

18 

SECURITY 

A 

FE 

3(2) 

]46 

9 

16 


Cl) For bit switches the length field is used to indicate 
the bit location within the byte. 

(2) For variable length fields the location field is used 
as a variable field index. 
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APPENDIX E. 

IHE POSITICN OF FIELDS STTHIN A PECOBD 

Fields are positioned in the data record in the order in 
which they are created as to the followinq alqoritbim. On 
the anchor and associated files the order is; 

1, RECLSN, 

2* anchor file Jcey field, 

3* record security field, 

4. all packed bit fields, 

5. all fixed length fields, 

6. all varying length and elemental fields. 

On subfiles the order by position is: 

1. PECLEK 

2# subfile key field, 

3. subfile parent key field, 

4. record security fields 

5. all packed bit fields, 

6« all fixed length fields, 

7* all varying length and elemental fields* 

The Descriptor Editor maintains three lists of fields for 
each descriptor region, one list for each of the folloiwinq 
field groups; 

1, packed bit fields, 

2, fixed length fields including ordinary or unpacked 
bit fields, 

3* varying length and elemental fields* 

The order within each field group is determined by the order 
in which the user creates fields within each group. This 
ordering may be changed through use of the MOVE command. 
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TOPIC D,3 - BDBLCAD - LOADING NEN FILES 


I. INTPODDCTICN 

The DBLOAD program is used for either initially loadina 
data onto a newly defined file, or for updating an 
existing file. In either case, the descriptors for 
the file most have been completely specified before any 
loading of data is attempted* The program is general 
in that each input record is passed to a specifically 
written sut-routine which identifies each of the fields 
that comprise the record, and passes this information 
back to DBIOAD fcr processing. 

This manual describes the mode of operation for DBIOAD, 
and the parameters necessary to invoke it. The 
procedures to follow for writing a DBLOAD exit routine 
are in this manual. 

II. INVOKING DBLOAD 

DBLOAD is invoked by entering the LOAD command to the 
maintenance sub-system. The format of the command is 
as follows: 

Command: ICAD 

Operand: 10AEMOtE=mode, 

ICADEXIT=exitname , 

KEyFHT=f orroattinq, 

LOAD ANC=anchor, 

LOACASSC=associat€, 

ICAESDB=sub, 

INVERTED=index, 

lOADINFT=input, 

GEN EBKIY= gen crate, 

EPBFILE=error , 

LCADEBBS=liffiit 


Nhere: 


mode 

identifies the mode of operation for the 
program. 

Specified as: a one character code, •!* for load 
mode, for update mode, and 'F* for restart 

mode* 


exitname 

identifies tie name of the user exit routine which 
is tc be called to describe the composition of 
each input record* 
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Specified as: a 1-7 character name of the user 

exit rcatine entry point, 

Eefault: the exit name is constructed by 

prefixing the file name with an ’X*, 


formatting 

identifies the name of the key field formatting 
routine. 


Specified as: 
character most 
characters must 


a 1-8 character name whose first 
be alphabetic and whose remaining 
be alphanumeric. 


anchor 

indicates whether the anchor file is to be 
loaded. 


Specified as: a one character code, for yes, 

and 'N* for no. 


Default; the anchor file will not be loaded. 


associate 

identifes the associate files to be loaded. 

Specified as; a multiple element parenthesi7ed 
list cf associated file suffixes (1,2,, ,,9) 


sub 

identifies the subfiles to he loaded. 

Specified as: a multiple element parenthesized 

list cf subfile suffixes (P,S,,,. ) 


index 

identifies the fields to be indexed with this 
load. 

Specified as: a multiple element parenthesized 

list of 1-8 character field names 
(FIELCl,FIEli:2,.,,) 

input 

identifies the fully qualified name cf the input 
dataset from which CBLOAD is to obtain its data. 

Specified as: a 1-35 character fully qualified 

dataset name. 

Default; the input dataset name is constructed by 
appendina the qualifier •, INPUT’ to the file 
name. 
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generate 

indicates vhether or not large nuaieric keys are to 
be generated for the outpnt data base* 

Specified as: a one character code, •¥■ to 

indicate that large nnmeric Jceys are to be 
generated, and to indicate not to generate 

keys. 

Default: Keys uill not be generated. 


error 

identifies the fully qualified name of the error 
dataset to which invalid input records are to be 
dumped • 

Specified as: a 1-35 character fully Qualified 
dataset name. 

Default: the error dataset name is constructed by 
appending the qualifier ’.EFPOB* to the file 
name. 


limit 

identifies the number of non-critical data errors 
that are allowed before terminating the program. 

Specified as: a 1-4 digit number. 

Default: a limit of 100 errors is established. 

Examples: 

1. The user wants to load a file with the anchor, 
associated files 1 and 2, subfiles Y and Z* The 
key has a formatting routine entry point name of 
DBF8T1N. No fields are to be indexed, Dser exit 
routine is YEXXT and input file DSNAME is 
INPDT.FXXE. 


SYSTEK: 
OSXP : 
SYSTER; 
OSEB ; 
SYSTEK: 
DSEB : 
SYSTER: 
TJSEE : 
SYSTER; 
OSEH : 
SYSTER: 
nSBB : 
SYSTEK: 


ENTEB: 

load 

ENTEB MODE: 

1 

ENTEB EXIT EOOTINE NAME: 
xexit 

ENTEB KEY EOBMATTXNG BOOTINE NAME: 
dbf ittln 

ABCHCB FILE TO BE LOADED (Y,N)?: 

y 

ENTEB ASSOCIATED EILES TO LOAD: 

( 1 , 2 ) 

ENTEB SDEEILES TO LOAD: 
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USES : 
SYSTEig: 
USEE ; 
SYSTEKs 
USER ; 
SYSTEP; 
USER : 
SYSTEP: 
USER ; 


(Yr^) 

ES*rER FIEir NAPES TO INVERT; 

ENTER INPUT DSNflPE: 
input* file 

GENERATE lARGE NOPEETC KEyS(H,Y)?; 
ENTER AIIORAEIE BaTABASE ERRORS; 


NOTE: User defaults fields to index to no fields, 

generate laroe numeric l^eys to no, error dataset 
name to FIIENAHE. ERROR, and data base allowable 
errors at ICC. 


2* The user wishes to restart the example above. 
First, the checkpoint backup copies should be 
catalcqued as the current data base files to 
insure data base integrity. 

The user could use the terminal support default 
and profile features so all the parameters will 
not have to be entered for each restart. The user 
can also enter the parameters as a string and not 
be prompted for them: 

SYSTEH: 

USER ; load L,xexit ,dbf mtln, y, < 1, 2) , 

(y,x) , , input. file 


III. OPERATING MODE 
A* Load Code 

DBLOAC opens the input dataset for input and the 
file fcr output and begins processing. 

B. Update Mode 

DBIOAE opens the input file for input and the 
output file for direct output and begins 
processing. 

C. Restart Mode 

DELOAt opens the file for update and reads the 
last record on the anchor file. It uses the key 
of this record to position itself in the input 
dataset. It then reads the next sequential input 
record. It is now ready to begin processing. 


IV. DBLOAD EXIT ROUTINES 
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Introduction 

CBLOAE passes each input data record to a user 
written exit routine for analysis before actually 
writinq any data to the file. This routine has 
the function of identifyinq each data field in the 
input record with a field name, indicating its 
starting location in the incut record^ and 
specifying the length of the data. If the data 
field is cn a subfile, the exit routine has to 
identify the subfile control field narae before 
any subfile fields can be put. Initial entry into 
the exit routine allocates the field name table 
and sets exit routine switches. 

Further, the routine can specify that the field 
should have leading and/or trailing blanks 

stripped off by DBICRD, that the field be skipped, 
that the record be skipped, that the load be 
terminated, or that subsequent calls to the exit 
routine be skipped. The latter is used to 
minimize oyerhead when each record to be processed 
has the sane physical characteristics. The 
routine must indicate when a new key is to be 
located to the output file. This is used in the 
case cf multiple inrut records for an output file 
key. 

When the update mode is used, the exit routine 
must indicate if this is a record to be deleted, a 
record to he replaced, or a record with fields to 
be replaced. 

B. Exit Routine Parameters 

The calling sequence used by DBLOAD to transfer 
ccntrcl to the exit routine is: 

CAIL exitname (input^data, user^ptr, 
bypass_switches) 


Where: 

exitmane 

is the entry point name of the routine to be 
called. 

input^data 

is a yarvinq length character string (maximum 
size - 4COO bytes) that contains the entire 
input data record, including the four-byte 
record length. 
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user^ptr 

is an external pointer that points to the 
user allocated structure containing the field 
naiaes, the field lengths, the field offsets, 
and the subfile field suffixes. 

by passes witches 

is a string of sixteen bit switches to be 
posted the exit routine to further define 
the status of the record for CBLOAE. The 
order and meanings of the various bits are; 

pyPASS_CfttL - bypass subsequent calls 

pypASS_RECOPD - bypass this record 

fCBWAPC_SCAN - delete leading blanks on 

fields 

E ACKWABC_SCAN - delete trailing blants on 

fields 

TEBHINATE^PGfl - terminate the program 
tEIETE^RECOPD - delete this record 
FEPLACE^FECOBD - replace this record 
OPDATE_BECOPD - replace fields within record 
NEW^KEY - locate this new key 

BITS 10-16 - unused by DBLOAB 

C. Exit Beutine User Structure 

fAPPENDTX A1 illustrates how to declare and use 
the user based structure. First, set the refer 
dimension egual to the maximum number of fields 
and elements (one field and a multi-element field 
with 10 elements would be 11> plus number of 
subfile control fields that may be assigned. Then 
allocate the based structure. Next assign the 
kev_name, the tey^ptr to the location of the key 
within the input record, and assign the key field 
lenath. Each entry into the exit routine will 
then reguire the field names to be assigned, the 
field pointers set to field locations within the 
record, the field sixes assigned, and the subfile 
suffixes assigned if field is a subfile control 
field, 

NOTES: 

1, The Key of the input record can be anywhere 
in the record, 

2, The input data record includes the record 
length field, 

3, large numeric keys can he generated for the 
output dataset if desired. 
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U* The nuiofcer of elements in the user structure 
is computed bv accumulating the total number 

of fields and/or elements in the input 

record, 

5, Anv field whose length is zero or whose 

pointer is null, is bypassed. If subfile 
suffix is not blank, A new subfile record is 
located. 

D. Sample DBIOAD EXIT Routine 

APPE^aDIX A illustrates the above narrative. The 
file has a key, one anchor file field, and two 
subfile fields with two elements each. The fields 
are all in field locations. After initial 

allocation, (first entry into exit routine) , the 
only processing required is to scan a record type 
field for the code used to indicate bypass of 

this record. Mote that all trailing blanks will 
be stripped off and that every input record has a 
new key and will have an output record located for 
it. The subfile control field *KID* has a null 
pointer and a field size of zero. The suh_suffix 
byte for this field gets assigned a *2' to 
indicate this is a subfile control field* 

CHECKPOINT BACKOP 

Because restart is very difficult after a TSS system 
crash, checkpoint backup of all the files is needed to 
insure data integrity between all the associated, 
index, subfiles, and anchor file that could exist 
during a load. When the user restarts a load after a 
system crash, he should make the last generation of the 
files current. This can easily be done by cataloging 
’BACKUP,* file (-1) as the current file. DBLOAD will 
call a sub-routine every 1,000 records to checkpoint 
the files. If the user can insure the data integrity 
after a crash (tbrouqb VIWHIZ utility or some other 
means) using backup copies will not be necessary. 

LOADING BUITI-FIIEE 

For the most efficient use of DBLOAD, only one file 
should be leaded on any given TSS userid at a time 
(such as the anchor file by itself, or one associate 
file by itself) « Other files for the same data base 
could then be loaded on other TSS userids at the same 
time. Also, data inteurity can be greater insured if a 
system crash occurs, because only one file exists on 
any given TSS userid, and file keys do not have to 
match (such as last anchor file key and associated file 
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. 

Subfiles should never be loaded independently of the 
anchor file, however. DBPAC must generate the subfile 
Jceys and post the subfile control field for each 
subfile record. 

Whenever possible HO field should be indexed while file 
is being loaded. The DEPAC inversion process is 
extremely involved and degrades the load process* It 
is extremely faster to load an entire file and then 
index the desired fields with the inversion command 
IHVERT. This command uses specialised techniques and 
the TSS sort utility to build the index files. 
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TOPIC B,4 - FIXE INVERSION - INEEXING 


I. INTRODUCTICN 

The NASIS inversion program (DBSIVPT) is a maintenance 
program for data base file creation. The pnrpose of 
the pccgtaff is to take data from certain fields of a 
data base and to pest this data to an index file. This 
operation can be done automatically by DBPAC during a 
normal file loading operation, but it is very time 
consuming and could therefore Jeopardize the 
successful completion of the load# Farther, by 
separating this function, the capability of creating 
indices after a file has been loaded and used is added 
to the repertoire cf the NASIS system. Finally, this 
separation also permits the use of specialised 
technigues suitable specifically to this function to 
reduce the amount of time required for the entire 
process of loading and index creation* 

This manual describes the mode of operation, invoking 
DBSIVRT, gives examples of use, and gives additional 
program notes. 

II. MODE OF OPERATION 

The inversion module can create up to ten index files 
simultaneously. Further, these files can each contain 
data from up to five separate but related fields. The 
module can process a specific number of input records, 
a range of input records, or the entire file. The 
module can be interrupted by the attention key at any 
time and program can then be terminated. Restart 
capability is provided at the field reading, sort, 
index file creation, and the index file translation 
steps. 

Step one reads a data base record, strips off the field 
being inverted, ccncatenates the field with the current 
anchor key, and record writes the concatenanted string 
on a YSAM data set. 

The sort step, invokes the TSS sort utility and outputs 
sorted VSAK file. 

Step three reads the sorted variable VSAM data set and 
creates a VISAN file. If the field is not indexed with 
external format, this file becomes the data base index 
file. 

Step four reads the VISA!! file created by step three, 
translates the keys using a field formatting routine. 
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and creates a translated index file. 

III. INVOKING SESIVNI 

DBSIVBT is invok€d tbrouah the maintenance sub-system 
by entering the ccmmand 'INVEST*. The format of the 
command is: 

Ccmmand: INVERT 

Operand: FIEID=field, 

HOCE=ffiod€^ 

PECCBDS= records, 

61N6E=ranqe 


Nhere: 

field 

identifies the field (s) to be indexed* 

Specified as: a 1-8 character name as entered in 

the file descriptors. Multiple fields must be 
entered as multiple element list. Fields being 
inverted to same index file must be kept 

together. 

Example: <A1,a2,a3,Bl,B2,C) First three fields 

go on same index file, fields B1, B2 gc on same 
index file, field C goes on index file by 
itself. 


mode 

identifies the program mode of operation. 

Specified as; a cne character code, 

F - initial pass, step one 

F - restart at step one 

S - restart at step two (sort step) 

3 - restart at step three 
T - restart at translation step 

Default; the initial pass (•?*) is assumed* 

records 

identifies the number of data base records to 
process. 

Specified as; 1-6 numeric characters. 

Default: 999,999 records (or entire data base). 


range 

identifies a range of file Keys to process. 
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Specified as: a nialtiple element list of two file 

keys, first key being the one to start at, second 
key being the one tc end at* 

Example: (KEY 05, KEY 10) Keys 5-10 will be 

inverted* 

Cefault: Entire file is assumed* 


EXAMPLES 


A* User wants to index AUTHORS field in one pass. 
User wishes tc be prompted for the parameters* 


USEE : invert 

SYSTEM : ESTER EIEIDS TO INDEX 

(flElt) <FTEU:,FII1D,. .*) : 


USER 

SYSTEM 

USER 

SYSTEM 

USER 

SYSTEM 

USER 


authors 

ENTER MODE (MODE) (F,R,S,3,T): 
f 

ENTER RECORDS TO PROCESS (RECORDS) t 

ENTER RANGE OF KEYS TO PROCESS (RANGE) 
(XXX, XXX) : 


NOTE: User defaults records to process to entire 

file* 

B. User wants tc invert ’MAJWORD* and ’MINBORD* on 
one index file, and •AUTHORS* on another index 
file* 


•USER’ : INVERT (MAJNOSC,flIN«ORD, AUTHORS) 

NOTE: User defaults program mode to initial pass, 

records to process to entire file, and range 
cf keys to entire file* 

V* PROGRAM NOTES 

A* Input dataset to sort step has a DSNAHE of 
S0STIN.FI1ENAME*FIE1D. 'FILENAME' is the six 
character data base name* 'FIELD' is the 1-8 
character field name* 

B* Cutput from sort step has a DSNAME of 

EORTOOT. FILENAME. FIELD. 

C, Innut file to translation step has a DSNAHE 
cf PLBX. FILENAME. FIELD. 

D. If range of keys specified, final output 
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index file has DSKfiME of 

PANGE.flliWAME.FIEtD. This dataset is used 
as input to the index mer<?e program. 

E, All SOartlN and SOBTOUT and PLEX datasets 
should fee erased after final index file is 
successful! y created, 

E, Invert as many fields as possible for any 
given file. This is most efficient for step 
cne of program since data base records only 
have to be accessed one time for multiple 
fields* 

G, Invert all associated fields separate as one 
pass. This is very efficient because only 
the associated file is accessed. 



PAGE 167 


TOPIC D,5 - Comfcine - Index Merging 


I, IMTSODUCTICN 

The index merge program (DEiNDR) is a special program 
for the mergina of index files. The user is oiven the 
option to process duplicate list elements or not, and 
to attention ard quit processing cleanly with a 
restart capability. 

This manual describes the mode of operation for DBINDH, 
the parameters used to invote EEISDM, gives examples of 
its use, and gives additional program notes. 

II, MODE OF OPFPATIOS 

The merger module can create a new index file, or it 
can merge in place to the current index file. The 
module can be interrupted by the attention key at any 
time and the program can be terminated* A restart 
capability is provided at any time during processing. 

III, INVOKING DEINDB 

DBINDH is invoked through the maintenance sub-system by 
entering the command •COMBINE. The format of the 
command is: 

COMMAND: COMBINE 

OPEPANE: MODI = FIP5TPASS 

BODE 1 = NEflFIIE 
FIEtC = FIELDNAME 
MODE 2 = EOPIICATES 


Where: 

Mode Identifies the program mode of operation. 

Specified as: a one character code, 

•!• - FIBSTPASS 
•E' - PESTAHT 

DEFADIT: SCKB. 

Mode 1 

Identifies the target merge file. 

Specified as: a one character code, 

• 1 ' - Rev file 
•0* - Inplace 


Field 
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Identifies the master index file. 

Specified as; 1-8 character name as entered in 
the file descriptors. 

Mode 2 

Indicates if duplicate list elements will fee 
processed or not. 

Specified as: a one character code^ 

- Process Duplicates 
*0* - No Duplicates Processed. 


IV. EXAMPLES 

A. A user wants to meroe index 

SABTLLY. APPCLIO. APOILOA, with 

RANGE-APCIIO.KEYNCBDS and create a new file with 
duplicates teinq processed. Processing duplicates 
will entail the posting of all matching index list 
elements as well as all other elements. 

USER : COMBINE 

SYSTEM: ENTER MCDE (EIBSTPASS , RESTART) F/R : 

USER : f 

SYSTEM: ENTER MCDE n=NEWFILE, 0=INPL ACE) : 

USER : 1 

SYSTEM: ENTER INVERTED FIELD NAME: 

USER : keywords 

SYSTEM; ENTER MODE (1 = PROCESS DUPSr0=NODUPS) : 

USER ; 1 

NOTE; User is required to respond to everv 
prompt. NONE may be skipped. 


V. PROGRAM NOTES; 

A. If the user wishes to merge in place, he should 
first make a copy of the current index file (for 
security reasons) • 

B. The input cr update index file to be merged is 
named RANGE. flLENAME. FIELDNAME. Check this before 
pECcessing is begun. 

C. When merging to a newfile the new file being 
created is called INDHRG. FILENAME. FIELDNAME. 

D. After the newfile is created and checked, it 
should replace the current index file, and the 
current index file should be erased. 
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TOPIC D,6 - CORBECT CCBflANE 


CORRECT in the maintenance suh-system updates a file 
on-line. The CCRRECT command allows the owner to examine 
the data contained in any of his files. After examining the 
data, the owner may then make additions, deletions or 
modifications to it. New files may be created by the 
maintenance CORRECT command, 

CORRECT COWHAND 

A, The CCRRECT Command 

The format for the CCRRECT command is as follows; 

Command; CORRECT 
Operand; <FI2LD=name> 

<,KEY*key> 

<,VERIFY=mode> 

Where: 

name 

identifies the field of the record which the 
user wishes to examine. 

Specified as; a 1-8 character data value, 

key 

identifies the record within the file which 
the user wishes to access. 

Specified as; a 1-255 character data value, 

mode 

identifies the mode of operation for this 
session. 

Specified as; ’YES*, if the user desires an 
automatic display of the updated data, 
following each CORRECT sub-command, or *NO*, 
if he does not, 

E, Sub-Commands 

The CORRECT Command recognizes the following 
sub-ccmmands: 

1, ACC 

2, CANCEL 

3, CORRECT 
ii. DELETE 
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5. DISPLRY 

6. END 

7. FIELDS 
e. INSEHT 
S. REPLACE 
10. VERIFY 

The sab*coinmaii<3s give the owner extensive 
capabilities for reviewing and correcting the data 
contained in a data base. The sub-commands allow 
the user to access the records of a file, either 
candomlv or sequentially, and to then examine the 
data contained in any or all of the fields of the 
selected record. 

NOTE: All data values entered as operands of 

CORRECT sut-coromands must not contain any 
embedded ccramas. Further, any leading blanks 
entered with an operand, are stripped off before 
syntax analysis. To overcome these restrictions, 
the user is permitted to enter operands as quoted 
strings. In this mode, all data within the 

beginning and ending quote is processed. 

(Embedded quotes must be represented as paired 
quotes, and are converted.) 



PAGE 171 


CORRECT ADE SubcomBandl 

The ABE sut-coomand allovs the user to add a ne« record 
to the file, or new data to an existing record- The 
new key value is entered with its key field name. 
Hultiple element fields can be entered as a 

parenthesized list- Data can be added to a null field 
or new elements can be added to a field- The format 
for the command is as follows: 

Command: ACD 

Operand; FIEID=data,FIEID= (data, data, data) , 
EIElC=data - 


Where: 

FIELD 

is the 1-8 character field name- 

data 

is the data value to be added* 


Specified as a 1-255 character data value 
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CORRECT CAKCEL Subcommand 

The CANCEL sub-cotrniand allovs the user to nullify any 
correcticns entered since the last CORRECT or INSERT 
sub-cocjffiand • The format for the command is as 
follows: 

Command: CANCEL 
Operand: (none) 
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COHBECT COPPECT Sulccffiffiand 

The COPPECT sub-coffitnand allovs the user to specify a 
new reccrd and/ot field which he wishes to exaioine, 
without returning to NASIS command mode. It provides 
the additional capability of accessing anchor records 
seguentially (fctward or backward) from a oiven point. 
The format for the command is as follows: 

Command: COPPECT 

Operand: new-field, new-key 

Where; 

new-f ield 

is the name of the nert field in the record to be 
examined* 

Specified as; a 1-8 character data value. 

Cefault: the same field name is used* 
new-key 

is the key of the next record to be accessed* 

Specified as: a 1-255 character data value, or, a 
signed integer value for sequential processina. 

Default: the same record is used* 
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COBBSCT DEIETE SutcoBiffland 

The DEtSTE sub-coffiiaand allows the user to delete from 
the record, an element, a range of elements, a field or 
the entire record itself. The format for the command 
is as follcwsT 

Command: DELETE 
Operand: element- list 

Where: 

element-list 

is the list of elements and/or element ranges to 
te deleted. 

Specified as: 1) RECOBD to delete the entire 

record; 2) En to delete an element (n is an 
integer identifying the element); 3) (En1,En2) to 

delete a range of elements (n1 and n2 are integers 
identifying the beginning and ending elements of 
the range) • 

Default: the entire field is deleted. 



PAGE 175 


COBfiECT EISPtAY Sutcomniand 

The DISPLAY sttfe-ccmiDanti allows the user to display the 
entire field in sections, to facilitate the situation 
where all of the data cannot be shown on the screen at 
once. The user laay *paqe* sequentially (forward or 
backward) through the data, or he Bay specify the 
element number at which he wishes the display to begin. 
The ccmnand format is as follows: 

Ccmmand: DISPLAY 
operand: data 


Where: 

data 

identifies the type of display which the user 
desires, sequential forward, sequential backward 
or positional. 

Specified as: 1) E for sequential backward; 2) En 
to display ftcm element n. 

Default: display sequentially forward. 



PAGE 176 


COFBECT ESr Subcommand 

The END sub-command allows the user to terminate 
CORBECT processing and return to NASIS command node. 
The format of the command is as follows: 

Command: END 
Operand? (none) 
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COBBECT flELDS Sulcomnand 

The FIEIDS sub-cofftnand allows the user to request a 
formatted display cf all of the field names associated 
with this data fcase« The format of the command is as 
follows: 

Command: FIEIES 
Operand: (none) 
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COPPECT INSEPT SufcconMDand 

The INSEET sub-ccirniand allows the user to specify 
subfile fields for adding a new subfile record, 
command format is as follows: 

Coromand: INSEPT 

Operand: FIElE=data,EIELD“data, • . « 

Where : 

FIEID 

is the subfile field name to be added, 

data 

is the data value of the field to be added, 
Soecified as: a 1-255 character data value. 


new 

The 
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CORRECT INSERT SufccoffimatJd 

The REPLACE sut-cc Hiraand allows the user to change data, 
contained in a field, by value. The format of the 
command is as follows: 

Command; EEPIACF 

Operand; start, end, old-data, new-data 
Rhere: 
start 

identifies the element number at which scanning 
for the old data string is to begin. 

Specified as: En where n identifies the element 
desired. 

Default; the current element number is used. 


end 


identifies the element at which scanning for the 
old data string is to end. 

Specified as: En where n identifies the element 

desired. 

Default: the last element is used, 
old-data 

identifies the existing data value. 

Specified as: a 1-255 character data value, 
new-data 

identifies the replacement data value. 

Specified as; a 1-255 character data value. 
Default; a null value is used. 



PAGE 180 


COBBECT VIBIPy Sntcofflfliand 

The VSBIF? sub-ccpwand allows the user to change the 
mode of operation for a typewriter terminal. The 
format of the command is as follows; 

Commard: VEBIFT 
Operand; mode 


Hhere: 


mode 


identifies the subsequent mode of operation. 


Specified as; *YES* if the user desires an 
automatic display of the updated data, following 
each CORRECT sub-command, or •BO* if he doesn’t. 
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TOPIC D*7 - BCBfiKTM - HIINTEBANCE - UPDATE 


!• TNTBODUCTICN 

The maintenance proqram (DBHNTH) is an independent 
module to te used for maintaining NASIS data bases. 
Maintenance consists of additions to, deletions from, 
or modifications cf the data contrained on a data base. 
Transactions are used to describe changes to data base 
records and are stored in the TENSCT Data Ease. The 
transactions can reference a particular record, field 
or element in describing the desired change. 

Data base maintenance is executed non-conversationallv, 
although it is invoked from a conversational terminal. 
It oust be run under the TSS userid of the owner of the 
data base being maintained. The program is restartable 
in that, each transaction processed successfully, is 
deleted frcn the transaction data base. 

This manual describes the operating procedures, the 
mode of operation, and the types of transactions 
supported. 

II. INVOKING MAINTENANCE 

NASIS maintenance is invoked by entering the command 
UPDATE to the maintenance sub-system* 

III. NAINTENANCE OPEBATING PROCEDURES 

The data base cwner may use the CORRECT comoand to 
peruse the transactions and to delete any which he 
deems tc be unneccessary or invalid (See CORRECT 
command User's Guide) . 

Once the transactions are determined to be acceptable, 
he is ready to initiate maintenance. Restart is 
similar, hut should require no transaction editing. 

IV. MODE OF OPFFATICN 

Maintenance initiation is a two-step procedure. The 
first step is the invocation of the program DBCLHN, 
DBCLMN creates a line data set, which will be used by 
the TSS command system as the input data set for the 
background maintenance task. The STSIN data set will 
be named CtDBMA IN. data base and will contain the CAlt 
necessary tc execute the maintenance program itself. 

The second part of the process is the actual execution 
of maintenance itself. This phase is always performed 
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in the ncc-ccnversational mode by executing the data 
set created by tECtWN, Earing this phase, the data 
base is opened for update, the transactions are opened 
for update and processing begins. Each transaction is 
handled separately and if successfully processed, the 
transaction is deleted. 
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TOPIC E.1 • TSPl/I LANGUAGE EXTENSION 


I, INTFODDCTICN 

The terroinal support preprocessor for NASIS (TS> allows 
the Pt/I crogtatBGr to include in his program, 
statements, in ncrmal PI/I syntax, which refer to and 
use the various terminal support functions. To enable 
the use of the TS preprocessor in a particular program, 
it is only necessary to insert the following 
statements 

% INCIUDE lISBHACfTS); 

This statement must appear before any actual use of the 
pre processor itself. 

The preprocessor functions available are listed in the 
appendix along with the terminal control block (TC) 
containing the various switches and control fields that 
are used tv terminal support. The functions crovided 
perform a set of generalized operations on the terminal 
device. These operations can be altered and refined by 
the setting of appropriate switches in the TC block 
before invoking the particular TS function. This 
alteration is most useful for the PUT and PFOHPT 
operations. 

In addition to the functions listed, terminal support 
has defined two interrupt conditions, RTTN and END, to 
facilitate prograoiter control of the terminal device. 
The ATTN conditicn is raised each time the user 
depresses the attention key on his terminal. Nhen this 
occurs, terminal support calls the last defined PL/I ON 
block for ATTN’s via the signal mechanism. If the ON 
block returns, terminal support will prompt the user 
for a command with the following message: 

-ATTN: 

The user mav respond to this message with any of the 
’’immediate” commands: 


SYNONyM 

SYNONyWS 

DEFAOIT 

DEEAOITS 

PFOIIIE 

EXPLAIN 

FSOMPT 

STRATEGY 

KA 
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KB 

B!ICK 

END 

APOFF 


GO 


A default response is interpreted as a Go. If during 
the executicn cf one of these commands, the user 
depresses the attention key, that comraand will be 
terainated and the user will be reproapted. 

The user nav define an ON ATTN block in his program, 
but he must adhere to the following restrictions^ 

1. Pe may only issue output TS functions. 

2. If he wants to suppress the system prompt, he 

must branch out of his ON block (by so doing, 
he cannot return to the point of 

interruption) , 

If the user wishes to disable attentions completely, he 
must set the *EISABLEC* hit in the system data table 
OSERTAB, (This action should only be taken in the most 
critical situations). 

In the above description, if the user had responded 
with an END command, terminal support would have raised 
the END condition via the signal mechanism. The 
purpose of this condition is to provide a standard 
method of terminating a program or application and yet 
allowing it to perform any ”clean-up” actions that are 
necessary. As with ATTN, any output TS messages will 
be allowed. 

The terminal support functions assume that the device 
has a screen, and that this screen is divided into an 
upper output area and a lower prompting area. The 
logical dimensions of the screen are defined by the 
physical diniensicns or the default values for the 
symbols SCBNHGT and SCRNNTH. The current dimensions of 
the screen can be found in the TC block during the 
execution of the program. 

STATEMENTS 

A. ENABXE <ATTN 1 END | ♦Att>; 

This statement causes the default coding for the 
END and/or ATTN conditions to be generated into 
the program. The default code for ATTN is to 
simply return to the point of interruption. The 
default code for END is to branch to a routine 
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that will ternsinate the program via a 5ETUSN, 

This statement, if present, must appear only once 
in the program and before any ENTRY statements. 
This statement also implies an ENTRY statement. 

E, ENTRY; 

This statement must be executed before any other 
TS statements, during a particular invocation of 
the program. It establishes the default ON 
blocks generated by ENABLE and calls terminal 
support to initialize the TC block* Because of 
its tuncticn, an ENTRY statement should appear at 
each entry point of a program, or at a common 
point in the processing for all entry points. 

An ENTRY need not follow an ENABLE, as the ENABLE 
statement includes and implies ENTRY. 

C. ON PAGE CAII(entry); 

This statement establishes the name of the routine 
which is to process paging of the screen for the 
current function. When a function has filled the 
screen with data and terminates with more data to 
be displayed, a PAGE command will result in a call 
to the entry point specified by the most recent ON 
PAGE statement. 

The "entry” parameter must be, or will be, 
converted to a character string of eight or fewer 
characters in length. 

D. PPOKPT HSG(k€v1 COSING (inserts) > <INTO (buffer) >; 

This statement has two functions, the outputting 
of a message (where the INTO clause is omitted) 
and prompting for a command. The message 
specified will be located in DBALIB(O) (IISRMLF) 
or LISPIIB(O) fllSRKLF) and displayed to the user. 
Any inserts specified will be placed in the 
proper positions within the text before it is 
displayed. If the message cannot be found, 
terminal support will automatically issue a 

diagnostic containing the message key. If a 
command prompt is indicated, the text will be 
preceded by a dash (-) and a string of {"; 
will be appended to it before it is displayed. 
All inserts will be stripped of leading and 
trailing blanks. Unspecified inserts will be 

replaced by «♦♦♦”, 
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The ”key" parameter must be, or will be converted 
to a character string of eight or fewer characters 
in length. The "inserts” parameter must be a list 
of twenty cr fewer character strings. The 
"buffer" parameter must be a character string into 
which the command entered is to be placed* It 
should be eight characters in length, or 
greater. 

If the ccmmand entered by the user, after synonym 
search, will not fit in the string specified by 
the user, TC. PROMPT. TBtJNCATION will be turned on 
by terminal soppcrt. Further, this, or any other 
type of error (syntax, etc.), will cause 
TC. PROMPT. ERECB to be turned on. 

PROMPT MSG (key) <DSING (inserts) > KEYWORD (id) 

INTO (buffer) ; 

This statement is used to request parameters 
and/or data from the user or from the profile. 

The "l^ey" parameter must be, or will be converted 
tc a character string of eight or fewer characters 
in length. The "inserts" parameter must be a list 
of twenty or fewer character strings. The "id" 
parameter must be, or will be converted to, a 
character string of eight or fewer characters in 
length. The "buffer" parameter must be a 
character string into which the data is to be 
placed. The maximum size data element returned by 
terminal support is 255 characters. 

If the TC. PROMPT. BYPASS bit is turned on by the 
user prior tc this statement, terminal support 
will examine the remaining parameters in its 
buffer and the profile for the data value, but 
will not prompt the user. Otherwise, if no value 
is found in the buffer or in the profile, the user 
will be prompted for the data value. If the "id" 
parameter is null and the data is specified in 
keyword format, terminal support will post the 
keyword into TC. PROMPT. KEYWORD for the user. If 
the program detects an invalid data value and 
wishes to reprompt the user for it, the 
TC. PROMPT. ERROR tit should be turned on prior to 
the PROMPT. If any errors are encountered by 
terminal support, the TC. PROMPT. ERROR bit will be 
turned on. If the data entered will not fit into 
the string specified, the TC.PROHPT.TEDNCATIOH bit 
will be turned on. If the value returned was 
obtained from the user^s profile, the 
TC. PROMPT. DEESULT bit will be turned on. 
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Likewise, if the value returned was a quoted 
string, the quotes will be removed and the 
TC.PRCMPl. STRING bit will be turned on. If the 
value returned is an element of a parenthesiTied 
list, only the element will be returned, and the 
TC. PROMPT. «ORE_DATA bit will be turned on. 
Subsecuent prompts will result in succeeding 
elements being returned, until the end of the list 
is reached. 

F. READ INTO (buffer) ; 

This statement causes the current contents of the 
screen to be returned to the user. 

The "buffer** parameter must be a character string 
into which tbe data is to be placed. 

G. HRITE PROM (buffet) ; 

This statement causes the screen to be written 
from the area specified, without any editing. 

The "buffet" parameter must be a character string 
which contains the data to be written. 

H. PUT <LINE I PAGI> FROM (buffer) <TAG (value) > 
<FOEHABD|EACKWARD>; 

This statement causes a new record to be placed 
into the screen buffer* 

The "buffer** parameter must be a character string 
which contains the data to be written. The 

"value" parameter must be a character string which 
is to be used to identify this output record, if 
LINE is specified, the record is sequentially 
added to the screen buffer. If PAGE is specified, 
the screen buffer is reset and this record becomes 
the first record of the new screen. The FORWARD 
and BACKWARD options are used to control the 
direction of the sequential filling of the screen 
buffer, from the top down, or from the bottom 
up. 

If the user*s data exceeds the width of the 
screen, the second and subsequent lines begin at 
the positicD indicated by TC. ODTPOT. INDENT. If 
the user*s data causes the screen to overflow, 
the amount of data written is indicated by 
TC. OUTPUT. WRITTEN. If the user wishes only 
complete records to be written to the screen, he 
should have TC.ODTPOT. PUT PARTIAL turned off. If 
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the user wishes the screen to be antoaiatically 
written when the buffer is filled, be should turn 
on the TC.COTPOT. ADTO^WRITE bit. If the user 
wishes to haue bis lines split between words (for 
tewt processinq) he should turn on the 
TC.OOTPDT.HOED^BPEAK bit. If the user has 
displayed a seoment of the current record on the 
previous paqe and he wants the reoaining segment 
tagged and/or indented, he must turn on the 
TC. OUTPUT. CONtIKDATION bit. If the last PUT 
caused the buffer to be filled, the 
TC.OUTPUT.OVERFLOW will be turned on, 

I. FlUSR; 

This statement is used to force the contents of 
the screen buffer to he written, even though it is 
not filled. If the user wants to indicate that 
more data remains to be displayed via the paging 
mechanism, he should turn on the 
TC. OUTPUT, POKE_l)&TA bit before his last output 
operation. 

J, FINISH; 

This statement causes the preprocessor to generate 
the necessary code to enable execution time 
communication with terminal support. It must be 
the last TS statement in the program. 
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TOPIC F,1 - LIMIT TABU OSER*S GUIDE 

The LIMIT table is used by the LIMIT command to determine 
the names of the anchor key subfields and where they are 
located within the anchor key. The limit table for a given 
data base must te defined by the DBA if the LIMIT command is 
to apply to this data base. These anchor key subfields may 
or may not he defined in the data base descriptor file. The 
LIMIT table is entirely independant of the descriptor 
file. 


The LIMIT structure is defined in the data set 
specif icaticns cf the CWB. This table is initialized by 
defining the followinq FL/I procedure whose name is defined 
as "L” concatenated to data base name; i.e. ”1SEIS". The 
module name is formed fcy concatenating “E’* to the procedure 
name; i. e. "RLEBTS”. This module is to reside in DBAITB. 

1 XXXXX: /* PPOCEDDRE NAME. */ 

PEOCEDURE; 

DCL I BIN PIXBC; /* NEEDED FOR PLI PROBLEM. ♦/ 

% INCLUDE LISEMAC (LIMIT) ; GET LIMIT TABLE. ♦/ 

IF -.ALLOCATION (LIMIT) THEN 
ALLOCATE (LIMIT) ; 

LIMIT. KEY ST E= (nnn) ; /»HHEEE (nnn) IS THE LENGTH */ 

/*Of THE EXTERNALLY */ 

/♦FORMATTED KEY. */ 

LIMIT.# ENTRIES^ (nnn) ;/*NHERE (nnn) IS THE NUMBER OF*/ 

/♦SOBFIELDS DEFINED ON THE ♦/ 

/♦ANCHOR KEY AND HENCE THE ♦/ 

/♦NUMBER OF ENTRIES IS THIS ♦/ 

/♦TABLE, ♦/ 

/♦MOTEtTHERE MUST BE A GROUP OP THE FOLLOWING THREE*/ 
/♦LINES CF CODE FOR EACH ANCHOR KEY SOBFIELD */ 

LIMIT. FIELD. NAME (i> = FIELDNAME; 

/♦THE ANCHOR KEY SUBFIEID ♦/ 

/♦NAME ♦/ 

LIMIT, FIELD.START (i) = (nnn) ; /*WHERE (nnn) IS THE */ 

/♦IS THE STARTING CHARACTER ♦/ 


/♦POSITION IN THE EXTERNALLY ♦/ 
/♦FORMATTED KEY OF THE ABOVE ♦/ 
/♦ANCHOR KEY SUBFIELD NAME, ♦/ 


LIMIT. FIELD. LNGTHfil =(nnn) ; /♦WHERE (nnn) IS THE */ 

/♦LENGTH IN CHARACTERS OF THE */ 
/♦ABOVE ANCHOR KEY SOBFIELD ♦/ 
/•NAME, */ 

/♦NOTE;THE ABOVE DEFINED SUBFIEID MUST BE WHOLLY ♦/ 
/♦CONTAINED WITHIN THE ANCHOR KEY FIELD. ♦/ 


END; 
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TOPIC G. 1 - USAGE STATISTICS 


I. INT50DUCTICN 

Dsaqe Statistics is, essentially, a separate sub-system 
of NASIS, whose function is to collect and retain 
statistics, conceivinq the use and status of the 
system* The statistics maintained are divided into 
retrieval statistics, use of the system, and 
maintenance statistics, status of the data. The 
retrieval statistics include counts of the number of 
times that various commands have been invoked, the 
number of retrieval sessions, the dates and time used 
for those sessions, as well as the aqqreqate time spent 
retrievinq data. The maintenance statistics include 
counts of the numbers of record additions, deletions 
and updates, for the anchor file, subrecord files and 
for all inverted indei files. 

The maintenance of these statistics is an automatic 
function and will not be discussed here. What will be 
covered bv this document is the production and use of 
the reports available throuqh Dsaqe Statistics. Tt 
should be noted that the retrieval statistics are 
available to any NASIS user, while the maintenance 
statistics are available to the owner of the dataplex 
only, 

II. STATISTICS CHECKPCI8T 

The statistics gathered for retrieval are maintained on 
a per session basis, with a capacity for thirteen 
sessions before re-initialization is necessary. 
Because of this, a check is made each time a new 
session is bequn, and if re-initialization is 
necessary, a checkpoint listing of the retrieval 
statistics is produced, so that the data on file will 
not be lost. 

The checkpoint report is a formatted list of the data 
on file for a particular NASISID, before 
reinitialization. It will contain a line entry for 
each of the sessions on record, displaying the command 
counts, the lines, the date, the file name, and other 
pertinent information. The DBA should examine this 
report to analyze the usage that NASISID is makinq of 
the system and of the individual dataplexes. If he 
deems that some action is necessary, e.g., a user is 
logged ontc the system for excessive periods of time, 
but not executing many commands, he should do whatever 
he feels is required. In any event, the report should 
be retained for future reference and analysis, and 
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should prolrablv be filed by NASISID* 

A sample checkpoint report is included in figure 1. 

III. RETRIEVAL STATISTICS REPORT 

Bv submitting JOB CCCSPRNTR, the status of the entire 
retrieval satistics file can be presented. This report 
displays the activity of the various NASISICS, the 
various data tases and the various retrieval 

comsands. 

The retrieval report is formatted by NASISID, with a 
line entry for each terminal session. These entries 
present the various ccmmand counts^ the lines, the file 
names, and other pertinert information. In addition, a 
summary is made, at the end, of the aggregate times and 
sessions for all users. 

A sample retrieval report is included in Figure 2. 

IV. maimtenancf statistics BEPCRT 

By submitting JOE CCCRPRTB, the status of the entire 
maintenance statistics file can be presented. This 
report should be used bv the REA to validate the 
maintenance records of each data base. Tn addition, it 
should be used tc assess the maintenance activity of 
the various dataplexes. with this information, the DBA 
will be in a better position to know the exact status 
of his dataplexes, when to backup the system, when to 
reorganize his files, and manv other questions that 
must be answered in order to maintain proper control 
over the system and its data. 

The maintenance report is formatted bv dataplex name, 
with a line entrv for each maintenance run. These 
entires present the counts of the number of additions, 
deletions and updates made to the anchor and associated 
files, the subrecord files and the inverted index 
files. In addition, a summary is made, for each file 
showing the aoqregate and the average number of 
additions, deletions and updates to the dataplex. 

A sample maintenance report is included in Figure 3. 
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DATAPLEX TOTAL ANCHOR NUMBER TRANS 

NAME TRNS RECORDS RUNS RUN 

ASRD1$ 3,132 1 


MAINTENANCE FILEPLEX 

DATES ADDS DELETES UPDATES ADDS 

12/19/72 3,132 


FILEPLEX 

ADDS 

DELETES 

TOTAL 

3,132 


AVERAGE 

3,132 



SUBPLEX XPLEX 

DELETES UPDATES ADDS DELETES UPDATES 
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FOR ALL RUNS 
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RETRIEVAL STATISTICS 
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NASISID 

NEOl 


CONN-TIME 

CPU-TIME 

// 

STRAT 

STORED 

OWNER 

FILE 

FIELD 

ACTUAL 

TOTAL 

NUMBER 

OFk 

HR:MM:SC 

HR:MM:SC:MS 

SES 

LENGTH 

# 

ID 

NAME 

NAME 

EXP 

SEL 

SRCH 

CORK 

0:53:30 

0:00:48:790 

5 

0 

0 













SAOWNER 

ASRD1$A 

AUTHOR 

3 . 

0 

0 
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KEYWORDS 

13 

0 

0 
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EMPAGE 

1 

0 

0 

0 
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1 

0 

0 
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1 

0 

0 

0 
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1 

0 

0 
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DB2TDBE 

SVCDATE 

1 

0 

0 

0 
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LISR ID CONN-TIME CPU-TIME # STRAT OWNER-ID FIELD FILE SESSION # // // // 

HR:MIN:SC HR:MN:SC:MS SES LENGTH NAME NAME DATE EXPANDS SELECTS SEARCHS CORRECTS 

•i). 

NEOl :19:40 0:00:12:399 2 SAOWNER KEYWORDS ASRDI$B 721215 

721215 1 
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721215 

721215 

721215 

721215 

721215 

721215 

721215 

721215 

721215 


721215 


1 
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BATCH PPINT MONITOR tJS£B*S GUIDE 
I* IRTPODUCTICN 

The Batch Print Wcnitcr is a completely independent set 
of proqrams which allows one terminal to selectively 
execute retrieval print tasks which have been queued by 
NASIS users* Execution of a print task implies 
identifyinq the specific print queue <by NASIS ID) and 
specifvinq the task to be run* Alternatively, the 
terminal user may invoke sequential processinq of all 
NASIS IDs and all cutstandinq print tasks. 

Printed listings are produced off-line and consist of 
information retrieved from a NASIS data base according 
to a format stored by the NASIS user. 

II. BATCH PPINT COMPANDS The Batch Print monitor runs under 
the MTT Monitor, lost as NASIS does, and is invoked by 
dialing a TSS/360 telephone number and entering: 

BEGIN PRINTS 

This will invoke the system and allow one of the 
following : 

A. PRINT - nasis-id, bsn 
where: 

”nasis*id** identifies which print queue (by 
NASIS-IC) is to be processed. 

Specified as: 

1. Any valid NASIS-IE, 

2. *AI1 - process all NASIS-TDs. 

”bsn” specifies the print task out of 
queue which is to be processed. 

Specified as: 

1. Any integer in the range 1-199. 

2. ♦Alt - process all outstanding batch 
sequence numbers. 

B. END - Terminates print monitor execution and 
logoff the task. 

C. HOID - nasis-id , bsn . Requests the monitor to 
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place the print tasl^ specified by ”tsn” and 
”nasis-id" (see PEINT command) in hold status and 
skip processing until a RELEASE command is 
issued* 

RELEASE - nasis-id, bsn. Inverse of the HOLD 
command • 

NUMBER - nasis-id. Reguests a ccunt of 
outstanding print tasks for the indicated 
"nasis^id** (See PRINT command). 

CANCEI - nasis-id, bsn* Causes a print task to 
be removed frcm the print queue. 



